نصب

افزودن Doconut به پروژهٔ .NET 8 شما

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

پیش‌نیازها

این بسته بر روی این پلتفرم‌ها اجرا می‌شود:

پلتفرمپشتیبانی
Windows x64 / x86بله
Linux x64، مبتنی بر glibc (Debian، Ubuntu، تصویر رسمی mcr.microsoft.com/dotnet/aspnet:8.0)بله
Alpine و توزیع‌های دیگر مبتنی بر muslخیر
macOSخیر

در لینوکس، قبل از باز شدن اولین سند، کتابخانهٔ پیکربندی فونت را نصب کنید:

bash
apt-get update && apt-get install -y libfontconfig1

در توزیع‌های RHEL، Fedora و مشابه، بسته fontconfig (dnf install -y fontconfig) است. این تنها بستهٔ سیستمی است که Doconut به آن نیاز دارد: کتابخانه‌های بومی که استفاده می‌کند داخل بستهٔ NuGet قرار دارند و libgdiplus نیازی نیست. صفحات با فونت‌های نصب‌شده بر روی سرور رسم می‌شوند، بنابراین برای اطلاعات دربارهٔ فونت‌ها و پیام‌های خطای لینوکس به بخش عیب‌یابی مراجعه کنید.

نصب بسته

bash
dotnet add package Doconut.NET8

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

bash
dotnet add package Doconut.NET8 --version 26.10.0

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

ثبت 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(); // حالت جلسه به یک حافظهٔ نهان نیاز دارد (MVC/Razor Pages در حال حاضر یکی اضافه می‌کند)
builder.Services.AddSession(); // امنیت سند Doconut بر پایهٔ حالت جلسه ASP.NET است

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

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

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

ویژگیپیش‌فرضتوضیح
ShowDoconutInfofalseهنگامی که true، درخواست بدون token بنر نسخه‌ای را به‌جای ۴۰۴ برمی‌گرداند. برای بررسی سریع مفید است؛ در محیط تولید غیرفعال کنید.
UnsafeModefalseهنگامی که true، بررسی امنیت سشن ASP.NET در درخواست‌های صفحه را نادیده می‌گیرد. در محیط تولید غیرفعال کنید.
MiddlewarePath"/doconut"مقدار هماهنگی برای نقطهٔ انتهایی صفحه‑تصویر. اعتبارسنجی می‌شود، اما به‌تنهایی شاخه‌ای را سوار نمی‌کند؛ آن را با نگاشت واقعی UseDoconut() و BasePath مشتری هم‌راستا نگه دارید.
ResourcesPath"/doconut-res"محل سرویس‌دهی به منابع جاسازی‌شدهٔ JS/CSS/تصویر.
LicensePath"" (empty string)مسیر فایل لایسنس. خالی بودن به معنای عبور به منبع بعدی، سپس جستجوی خودکار است.
LicenseContent"" (empty string)محتوای خام لایسنس — از یک متغیر محیطی، یک مدیر راز، یا یک پایگاه داده.
LicenseStreamnullلایسنس به‌صورت جریان، یک بار در زمان راه‌اندازی خوانده می‌شود.
ResetLicensefalseپرچم سازگاری رزرو شده. سرویس‌های فعلی .NET 8 لایسنس را در زمان 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;          // امنیت جلسه را فعال نگه دارید
    options.ShowDoconutInfo = false;
});

گام‌های بعدی

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