Panduan Cepat

Render dokumen pertama Anda di MVC 5 atau Web Forms

Panduan ini mengambil aplikasi ASP.NET pada .NET Framework 4.7.2 dari paket yang terpasang hingga dokumen yang dirender di browser: Global.asax, endpoint pembuka, aset penampil, widget, dan token yang menghubungkannya. Ini mengasumsikan pendaftaran Web.config dari Instalasi sudah ada — tanpa handler DocImage.axd dan modul sumber daya, tidak ada yang di bawah ini dapat menjangkau server.

Susun Doconut di Global.asax

Sebuah Application_Start lengkap untuk aplikasi MVC 5:

csharp
// Global.asax.cs - susun sekali per proses pekerja, lepaskan saat shutdown.
protected void Application_Start()
{
    Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
        options.UnsafeMode  = false; // sebuah halaman hanya disajikan ke sesi yang membuka dokumen
    });

    // hanya MVC: jaga agar dua endpoint Doconut tidak masuk ke routing.
    RouteTable.Routes.IgnoreRoute("{resource}.axd/{*pathInfo}");
    RouteTable.Routes.IgnoreRoute("doconut-res/{*pathInfo}");
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}
  • Encoding.RegisterProvider membuat halaman kode warisan yang digunakan oleh beberapa format dokumen tersedia bagi proses. Panggil sekali, sebelum dokumen pertama dibuka.
  • UnsafeMode = false adalah nilai default, dituliskan agar tidak ada yang mengubahnya secara tidak sengaja: DocImage.axd menyajikan halaman hanya ke sesi ASP.NET yang membuka dokumen.
  • Dua pemanggilan IgnoreRoute menjaga routing MVC menjauh dari DocImage.axd dan /doconut-res/*, yang dilayani oleh handler dan modul. Aplikasi Web Forms tidak memiliki rute MVC dan tidak memerlukan baris tersebut.
  • DoconutHost.Shutdown menghentikan pekerjaan latar belakang Doconut dan melepaskan layanannya ketika pool aplikasi di‑recycle. Aman dipanggil bahkan jika Initialize tidak pernah dijalankan.

Buka sebuah dokumen

Membuka sebuah dokumen mengembalikan token yang tidak dapat dibaca. Widget mengirim token tersebut dengan setiap permintaan halaman.

Di MVC 5, aksi controller mengambil layanan Viewer dari DoconutHost.Services — MVC 5 tidak memiliki injeksi konstruktor untuknya:

csharp
// POST /Document/Open
[HttpPost]
public async Task<ActionResult> Open()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

    // Token tidak dapat dibaca - berikan ke penampil, jangan pernah log atau simpan.
    string token = await viewer.OpenDocumentAsync(Server.MapPath("~/files/Sample.pdf"));
    return Json(new { token });
}

Dokumen harus dibuka di dalam permintaan yang memiliki status sesi, karena pembukaannya yang memberikan sesi ASP.NET saat ini akses ke halamannya. Controller MVC dan halaman Web Forms memiliki status sesi secara default. IHttpHandler khusus tidak memilikinya, kecuali mengimplementasikan System.Web.SessionState.IRequiresSessionState. Membuka dokumen dari handler tanpa sesi, dan penampil akan menampilkan "Anda Tidak Diizinkan Untuk Melihat Halaman Ini." pada setiap halaman.

Di Web Forms, halaman itu sendiri dapat membuka dokumen di code‑behind‑nya. OpenDocument adalah bentuk sinkron dari OpenDocumentAsync, ditujukan untuk code‑behind yang tidak menggunakan halaman asinkron:

csharp
// Default.aspx.cs
protected string Token;

protected void Page_Load(object sender, EventArgs e)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    Token = viewer.OpenDocument(Server.MapPath("~/files/Sample.pdf"));
}

Perlakukan token seperti kredensial bearer: jangan pernah log atau simpan; berikan hanya ke widget. Token tidak akan berfungsi lagi ketika sesi dokumen kedaluwarsa — buka kembali dokumen untuk mendapatkan token baru.

Referensi aset penampil

Viewer.ReferenceCss dan Viewer.ReferenceScripts menghasilkan tag <link> dan <script> untuk aset yang disematkan, dalam urutan ketergantungan, mengarah ke /doconut-res/. Widget ini adalah plugin jQuery, jadi jQuery datang pertama.

MVC 5. Tampilan tidak memiliki @inject, jadi buat tag di controller dan kirimkan lewat ViewBag:

csharp
public ActionResult Index()
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
    {
        IncludeBootstrapCss = true,
        IncludeViewerCss    = true
    });
    ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
    {
        IncludeJQuery        = true,
        IncludeBootstrap     = true,
        IncludeViewerScripts = true
    });
    return View();
}
html
@Html.Raw(ViewBag.ViewerCss)
...
@Html.Raw(ViewBag.ViewerScripts)

Simpan pekerjaan itu di controller. MVC 5 mengompilasi tampilan ketika pertama kali disajikan, dan tanpa paket kompiler tambahan kompiler tersebut hanya memahami C# 5 — tidak ada ?., tidak ada $"...", tidak ada nameof. Sebuah tampilan yang menggunakan mereka akan terkompilasi bersih di Visual Studio, kemudian mengembalikan 500 kosong di peramban.

Web Forms. Ekspose string yang sama dari kode-behind dan tulis mereka dengan <%= %>:

html
<head>
    <%= ViewerCss %>
</head>
<body>
    ...
    <%= ViewerScripts %>
</body>

IncludeViewerCss dan IncludeViewerScripts adalah inti wajib. Untuk menambahkan pita Pencarian dan Anotasi, juga atur IncludeSearchCss, IncludeAnnotationCss, IncludeSearchScripts, IncludeSearchBar, IncludeAnnotationScripts, dan IncludeAnnotationBar. Kedua metode mengabaikan file pita ketika lisensi tidak memberikan kemampuan tersebut; penampil itu sendiri tetap berjalan.

Tambahkan penampil ke halaman

Permukaan rendering terdiri dari dua div bersarang:

html
<div id="divDocViewer">
    <div id="div_ctlDoc"></div>
</div>

Berikan div luar tinggi yang sebenarnya — penampil mengisi kontainernya dan mengukurnya saat dimulai. Penampil tidak menggambar toolbar-nya sendiri: GotoPage, Next, Zoom, FitType dan sisanya adalah metode yang halaman Anda hubungkan ke tombolnya sendiri, ditempatkan di samping penampil:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <button type="button" onclick="objViewer.GotoPage(1)">First</button>
    <button type="button" onclick="objViewer.Next(false)">Previous</button>
    <button type="button" onclick="objViewer.Next(true)">Next</button>
    <button type="button" onclick="objViewer.Zoom(false)">Zoom out</button>
    <button type="button" onclick="objViewer.Zoom(true)">Zoom in</button>
    <button type="button" onclick="objViewer.FitType('width')">Fit width</button>
</nav>

Inisialisasi penampil dan tampilkan dokumen

Setelah skrip penampil, buat widget, lalu berikan token kepadanya:

javascript
var objViewer = $('#div_ctlDoc').docViewer({
    showThumbs: true,
    autoLoad:   false,
    pageZoom:   100,
    FitType:    'width',
    BasePath:   '/',                   // '/' berarti DocImage.axd di akar situs
    ResPath:    'doconut-res/images',  // tanpa '/' di depan
    onViewerReady: function () {
        // halaman terlihat; sembunyikan indikator pemuatan di sini
    },
    onError: function (message) {
        console.error('Doconut viewer error:', message);
    }
});

fetch('/Document/Open', { method: 'POST' })
    .then(function (resp) { return resp.json(); })
    .then(function (data) { objViewer.View(data.token); });

Di Web Forms, di mana halaman membuka dokumen sendiri, tiga baris terakhir menjadi objViewer.View('<%= Token %>');.

Empat detail di sini gagal tanpa pesan error:

  • BasePath: '/' mengarah ke DocImage.axd di akar situs. Untuk aplikasi dalam direktori virtual, gunakan namanya tanpa garis miring ('myapp' meminta /myapp/DocImage.axd). Garis miring di depan ('/myapp') menghasilkan //myapp/DocImage.axd, yang dibaca peramban sebagai permintaan ke host lain.
  • ResPath: 'doconut-res/images' — ikon berada satu folder di bawah akar sumber daya. Dengan 'doconut-res', setiap ikon mengembalikan 404: tidak ada glyph toolbar dan tidak ada spinner pemuatan, sementara dokumen itu sendiri tetap ditampilkan. Garis miring di depan memecahnya dengan cara yang sama seperti BasePath.
  • Callbacks adalah opsi. onViewerReady, onError, dan sisanya masuk ke dalam objek yang diberikan ke docViewer(...). Fungsi global yang dinamai setelah penampil, seperti ctlDoc_ViewerReady, tidak pernah dipanggil.
  • Pertahankan penampil, lalu panggil View secara terpisah. docViewer(...) mengembalikan objek dengan Zoom, Next, dan FitType; View(...) mengembalikan sesuatu yang lain. var objViewer = $('#div_ctlDoc').docViewer({...}).View(token) merender dokumen, lalu gagal dengan objViewer.Zoom is not a function pada klik toolbar pertama.

Nama opsi mencampur camelCase (showThumbs, autoLoad, pageZoom) dan PascalCase (FitType, BasePath, ResPath). Opsi yang salah eja diabaikan, dan widget menggunakan nilai defaultnya.

Alternatif satu baris

Untuk halaman yang hanya perlu menampilkan dokumen, tanpa toolbar milik Anda, Viewer.RenderViewer menulis seluruh skrip inisialisasi — docViewer(...) dengan BasePath: '/' dan ResPath: 'doconut-res/images', kemudian .View(token). Itu hanya ada dalam paket ini:

csharp
// Kode-behind Web Forms, setelah membuka dokumen
ViewerInit = viewer.RenderViewer("div_ctlDoc", Token);
html
<div id="div_ctlDoc" style="height: 100vh"></div>
<%= ViewerScripts %>
<%= ViewerInit %>

Berikan ViewerConfig sebagai argumen ketiga untuk mengubah zoom, penyesuaian, atau panel thumbnail. Karena skrip yang dihasilkan tidak menyimpan referensi ke viewer, gunakan inisialisasi yang ditulis secara manual di atas ketika halaman Anda memerlukan toolbar sendiri.

Tutup dokumen

Panggil objViewer.Close(true) ketika pengguna meninggalkan viewer atau membuka pengganti: itu membersihkan widget dan mengirim permintaan penutupan ke DocImage.axd. objViewer.Close() tanpa argumen hanya membersihkan widget. Di server, viewer.CloseDocument(token) menghapus sesi dokumen sekaligus, melepaskan sumber daya renderingnya, dan mencabut akses sesi ke halaman-halamannya. Kedaluwarsa bergulir pada akhirnya melakukan hal yang sama, tetapi menutup dokumen besar secara eksplisit membebaskan memori lebih cepat.

Jalankan

Letakkan file PDF di ~/files/Sample.pdf, jalankan situs di IIS Express (F5 di Visual Studio), dan buka halaman yang menampung widget. Halaman pertama dirender, dengan thumbnail di sebelah kiri. Jika tidak, lihat Pemecahan Masalah.

Apa yang Anda dapatkan tanpa lisensi

Lisensi yang hilang tidak menyebabkan error. Viewer merender secara normal, tetapi setiap halaman menampilkan watermark evaluasi. Lihat Pengaturan Lisensi untuk mengetahui di mana Doconut mencari lisensi Anda.

Apakah halaman ini membantu?