ساخت یک مدیر فایل رایگان ASP.NET MVC که PDFها را نمایش می‌دهد

شما به صفحه‌ای نیاز دارید که فایل‌های ذخیره‌شده بر روی سرور را فهرست کند، به کاربر امکان دانلود یا حذف آن‌ها را بدهد و هر PDF را در مرورگر باز کند بدون اینکه سایت را ترک کند. راهنمای زیر نشان می‌دهد چگونه دقیقاً این کار را با ASP.NET MVC ساده، کش سشن داخلی، و نمایشگر جامع Doconut انجام دهید.

---

1. ایجاد یک برنامه MVC حداقلی

یک پروژه MVC جدید در Visual Studio ایجاد کنید (هر نسخه‌ای، از جمله نسخه رایگان Community).

یک FileController اضافه کنید که عملیات‌های مدیر فایل را میزبانی کند:

public class FileController : Controller
{
    private readonly string _root = Path.Combine(Directory.GetCurrentDirectory(), "App_Data", "Docs");

    public IActionResult Index()
    {
        var files = Directory.GetFiles(_root).Select(Path.GetFileName).ToList();
        return View(files);
    }

    public IActionResult Download(string name)
    {
        var path = Path.Combine(_root, name);
        if (!System.IO.File.Exists(path)) return NotFound();
        var mime = "application/octet-stream";
        return PhysicalFile(path, mime, name);
    }

    public IActionResult Delete(string name)
    {
        var path = Path.Combine(_root, name);
        if (System.IO.File.Exists(path)) System.IO.File.Delete(path);
        return RedirectToAction(nameof(Index));
    }

    public async Task<IActionResult> ViewPdf(string name)
    {
        var path = Path.Combine(_root, name);
        if (!System.IO.File.Exists(path)) return NotFound();

        // The viewer token is created here (see section 2)
        var token = await _viewer.OpenDocumentAsync(
            path,
            new Doconut.PdfConfig { AllowSearch = true },
            new DocOptions(),
            CancellationToken.None);

        ViewBag.Token = token;
        ViewBag.BasePath = "doconut";          // matches the middleware branch
        ViewBag.ResPath = "doconut-res/images";// embedded resources
        return View();
    }

    private readonly Doconut.Viewer _viewer;
    public FileController(Doconut.Viewer viewer) => _viewer = viewer;
}

کنترلر سه کار انجام می‌دهد:

1. Index – پوشه App_Data/Docs را می‌خواند و نام فایل‌ها را به یک ویو می‌فرستد.
2. Download / Delete – اکشن‌های استاندارد MVC که از helper داخلی PhysicalFile استفاده می‌کنند.
3. ViewPdf – PDF انتخاب‌شده را با Doconut باز می‌کند، توکن امنیتی دریافت می‌کند و آن را به یک ویو Razor می‌فرستد.

---

2. پیکربندی وضعیت سشن و سرویس‌های Doconut

نمایشگر Doconut برای محافظت از توکنی که یک سند را شناسایی می‌کند، به وضعیت سشن ASP.NET وابسته است. سرویس‌های مورد نیاز را در Program.cs (یا Startup.cs برای پروژه‌های .NET 6) اضافه کنید:

var builder = WebApplication.CreateBuilder(args);

// MVC services
builder.Services.AddControllersWithViews();

// Session cache – required for token validation
builder.Services.AddDistributedMemoryCache();
builder.Services.AddSession();

// Doconut registration – point to your license file
builder.Services.AddDoconut(options =>
{
    options.LicensePath = Path.Combine(AppContext.BaseDirectory, "wwwroot", "Doconut.Viewer.lic");
    options.MiddlewarePath = "/doconut";
    options.ResourcesPath = "/doconut-res";
    options.UnsafeMode = false; // keep the default security
});

var app = builder.Build();

// Session must run before the viewer middleware
app.UseSession();

// The Doconut middleware must be mapped to the path configured above.
// See Doconut documentation for the exact mapping call (e.g., app.Map("/doconut", …)).

app.UseRouting();
app.UseEndpoints(endpoints => endpoints.MapDefaultControllerRoute());

app.Run();

نکات کلیدی:

• AddDistributedMemoryCache یک ذخیره‌سازی در‑حافظه فراهم می‌کند که AddSession به آن نیاز دارد.
• UseSession() باید قبل از میدل‌ویر Doconut قرار گیرد؛ در غیر این صورت خطای زمان اجرا «Session middleware not configured.» را مشاهده خواهید کرد.
• MiddlewarePath و ResourcesPath رشته‌های هماهنگی هستند – شاخه میدل‌ویر واقعی باید با مسیری که پیکربندی می‌کنید مطابقت داشته باشد.

3. ایجاد نمای مدیر فایل

فایل Views/File/Index.cshtml را ایجاد کنید. این نما فهرست فایل‌ها را نمایش می‌دهد و اقداماتی برای دانلود، حذف و مشاهده PDF فراهم می‌کند.

@model List<string>
<h2>Document Library</h2>
<table>
    <thead><tr><th>Name</th><th>Actions</th></tr></thead>
    <tbody>
@foreach (var f in Model)
{
    <tr>
        <td>@f</td>
        <td>
            <a asp-action="Download" asp-route-name="@f">Download</a> |
            <a asp-action="Delete"   asp-route-name="@f">Delete</a> |
            @if (Path.GetExtension(f).Equals(".pdf", StringComparison.OrdinalIgnoreCase))
            {
                <a asp-action="ViewPdf" asp-route-name="@f">View PDF</a>
            }
        </td>
    </tr>
}
    </tbody>
</table>

زمانی که کاربر روی View PDF کلیک می‌کند، اکشن ViewPdf یک توکن ایجاد می‌کند و نمای دوم را برمی‌گرداند که ویجت مشاهده‌کننده را میزبانی می‌کند.

---

4. رندر Viewer Doconut

فایل Views/File/ViewPdf.cshtml را ایجاد کنید. این صفحه فقط به یک عنصر container نیاز دارد؛ ویجت جاوااسکریپت از منابع تعبیه‌شده بارگذاری می‌شود.

@{
    var token = ViewBag.Token as string;
    var basePath = ViewBag.BasePath as string;
    var resPath = ViewBag.ResPath as string;
}
<h2>PDF Preview</h2>
<div id="div_ctlDoc"></div>

<script src="@($"{basePath}/docViewer.js")"></script>
<link rel="stylesheet" href="@($"{basePath}/docViewer.css")" />

<script>
    $('#div_ctlDoc').docViewer({
        AccessToken: '@token',
        BasePath: '@basePath',
        ResPath: '@resPath',
        FitType: 'width',
        showThumbs: true,
        autoLoad: true,
        onError: function (msg) { console.error(msg); }
    });
</script>

ویجت AccessToken که شما فراهم کرده‌اید را می‌خواند، به نقطه انتهایی /doconut/DocImage.axd تماس می‌گیرد و هر صفحه را به صورت تصویر استریم می‌کند. از آنجا که توکن به نشست فعلی ASP.NET وابسته است، کاربر نمی‌تواند URL را کپی کند و سند را از مرورگر دیگری بدون کوکی نشست یکسان مشاهده کند.

---

5. مدیریت انقضای توکن و امنیت

زمان‌انقضای پیش‌فرض توکن در Doconut ۶۰ دقیقه است (قابل تنظیم از طریق DocOptions.TimeOut). اگر Viewer پیام «Document session not found» یا «You Are Not Authorized To View This Page» را دریافت کند، نشست یا منقضی شده است یا درخواست از یک زمینه مرورگر متفاوت می‌آید.

راه‌حل‌های معمول:

• Refresh the page – کنترلر یک توکن جدید تولید خواهد کرد.
• Increase the timeout – هنگام باز کردن سند یک DocOptions سفارشی پاس دهید:

var options = new DocOptions { TimeOut = TimeSpan.FromHours(2) };
var token = await _viewer.OpenDocumentAsync(
    path,
    new Doconut.PdfConfig { AllowSearch = true },
    options,
    CancellationToken.None);

• Cross‑origin setups – اطمینان حاصل کنید که ویژگی SameSite در کوکی نشست با دامنه فرانت‌اند شما سازگار باشد. مقدار پیش‌فرض Lax برای اکثر پورتال‌های هم‌منبع کار می‌کند.

---

6. گسترش مدیر (اختیاری)

مدیر فایل اصلی در حال حاضر کارآمد است، اما ممکن است بخواهید موارد زیر را اضافه کنید:

• Upload – یک فرم ساده که یک IFormFile ارسال می‌کند و آن را در _root ذخیره می‌کند.
• Folder navigation – اکشن Index را تغییر دهید تا مسیر نسبی را بپذیرد و آن را در برابر عبور از مسیرهای دایرکتوری (Path.GetFullPath + بررسی StartsWith(_root)) محافظت کنید.
• Search – files را بر اساس نام فیلتر کنید قبل از ارسال به نما.

تمام این افزونه‌ها در همان الگوی MVC باقی می‌مانند و همچنان از Viewer Doconut که توسط نشست محافظت می‌شود، بهره می‌برند.

---

7. آنچه به دست آورده‌اید

• یک مدیر فایل ASP.NET MVC رایگان – بدون کتابخانه‌های UI شخص ثالث، بدون هزینه‌های لایسنس.
• رندر PDF در مرورگر از طریق Viewer عمومی Doconut، که نیاز به نصب Office یا Adobe بر روی کلاینت را حذف می‌کند.
• دسترسی امن مبتنی بر توکن که از وضعیت نشست ASP.NET استفاده می‌کند و از به‌اشتراک‌گذاری دلخواه URL جلوگیری می‌کند.
• یک پایه کد واحد که برای .NET 6 و .NET 8 کار می‌کند و می‌تواند به Razor Pages یا APIهای مینیمال منتقل شود؛ تنها فراخوانی‌های ثبت‌نام (AddDoconut، UseSession) نیاز به تغییر دارند.

برنامه را به IIS، Azure App Service یا Docker مستقر کنید – پیکربندی یکسان Program.cs در همه جا کار می‌کند زیرا Doconut بر روی .NET 6+ اجرا می‌شود و نیازی به هیچ‌یک از اجزای بومی Office ندارد.