نصب

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

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

الزامات

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

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

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

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

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

در Docker، ترجیحاً از aspnet:6.0-bookworm-slim (Debian 12) استفاده کنید: برچسب پیش‌فرض aspnet:6.0، Debian 11 است که آینه‌های بسته آن ممکن است نصب libfontconfig1 را شکست دهند. صفحات با فونت‌های نصب‌شده بر روی سرور رسم می‌شوند، بنابراین برای فونت‌ها و پیام‌های خطای لینوکس به عیب‌یابی مراجعه کنید.

نصب بسته

bash
dotnet add package Doconut.NET6

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

bash
dotnet add package Doconut.NET6 --version 26.10.0

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

شناسایی یکپارچه‌سازی قبل از به‌روزرسانی

شناسه بسته Doconut.NET6 هم توسط یکپارچه‌سازی کلاسیک و هم توسط یکپارچه‌سازی فعلی .NET 6 استفاده شده است. از انتخاب مستندات فقط بر پایه نام بسته خودداری کنید:

  • DocImage.axd، new Viewer(_cache, _accessor, ...)، synchronous OpenDocument(...)، و اسکریپت‌های نمایشگر کپی‌شده دستی، یکپارچه‌سازی کلاسیک را شناسایی می‌کنند؛
  • AddDoconut()، UseDoconutResources()، یک Viewer تزریق‌شده، و OpenDocumentAsync(...) یکپارچه‌سازی فعلی مستند شده در اینجا را شناسایی می‌کنند.

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

ثبت Doconut

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

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

گام‌های بعدی

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