نصب
افزودن 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 ۴.۷.۲ دارد.
نصب پکیج
dotnet add package Doconut.NETStandardدستور بدون نسخه آخرین نسخه پایدار را نصب میکند. برای قفل کردن نسخهای که این مستندات توصیف میکند، نسخه را بهعنوان گزینهای جداگانه پاس دهید:
dotnet add package Doconut.NETStandard --version 26.10.0Doconut.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 اعتبارسنجی میکند.
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 قرار دارد:
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 ویژگیهای قابل تنظیم زیر را میپذیرد. هر یک اختیاری است — مقادیر پیشفرض زیر زمانی اعمال میشوند که یک ویژگی تنظیم نشده بماند.
| ویژگی | پیشفرض | توضیح |
|---|---|---|
ShowDoconutInfo | false | وقتی true، درخواست بدون token بنر نسخه را بهجای ۴۰۴ برمیگرداند. برای بررسی سریع مفید است؛ در محیط تولید غیرفعال کنید. |
UnsafeMode | false | وقتی true، بررسی امنیت سشن ASP.NET در درخواستهای صفحه را نادیده میگیرد. در محیط تولید غیرفعال کنید. به املا توجه کنید — کتابخانهٔ قبلی این را UnSafeMode مینامید. |
MiddlewarePath | "/doconut" | مقدار هماهنگی برای نقطهٔ پایان صفحه‑تصویر. اعتبارسنجی میشود، اما بهتنهایی شاخهای ایجاد نمیکند؛ آن را با نگاشت واقعی UseDoconut() و کلاینت BasePath همراستا نگه دارید. |
ResourcesPath | "/doconut-res" | منبعی که منابع جاسازیشده JS/CSS/تصویر از آن سرو میشوند. |
LicensePath | "" (رشتهٔ خالی) | مسیر فایل لایسنس. خالی بودن به معنای عبور به منبع بعدی، سپس جستجوی خودکار است. |
LicenseContent | "" (رشتهٔ خالی) | محتوای خام لایسنس — از یک متغیر محیطی، مدیر رازها یا پایگاه داده. |
LicenseStream | null | لایسنس بهصورت جریان، یکبار در استارتاپ خوانده میشود. |
ResetLicense | false | پرچم سازگاری رزرو شده. لایسنس در زمان AddDoconut() خوانده میشود؛ پس از تعویض لایسنس برنامه را مجدداً راهاندازی کنید. |
MaxConcurrentEditorSessions | 200 | حداکثر تعداد جلسات ویرایشگر زنده (سندهای باز شده با DocOptions.EditMode). بالاتر از آن، کمترین استفادهشدهٔ جلسهٔ بیکار بسته میشود. جلسات نمایشگر معمولی حساب نمیشوند. 0 یا مقدار منفی به معنای عدم محدودیت است. |
EditorSnapshotEveryOps | 50 | با فعالسازی پایداری ویرایشگر (AddDoconutEditorPersistence)، هر N تغییر ثبتشده، سند زنده را اسنپشات میکند. 0 یا مقدار منفی هرگز در میانهٔ جلسه اسنپشات نمیگیرد. وقتی پایداری غیرفعال باشد، هیچ اثری ندارد. |
اولویت لایسنس وقتی بیش از یک منبع تنظیم شده باشد: LicenseStream بر LicenseContent ارجحیت دارد، سپس LicensePath و در نهایت جستجوی خودکار — ببینید راهاندازی لایسنس.
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;
});گامهای بعدی
- شروع سریع — اولین سند خود را باز کنید و در مرورگر رندر کنید.
- راهاندازی لایسنس — جایی که Doconut به دنبال فایل لایسنس شما میگردد.
آیا این صفحه مفید بود؟