Instalasi

Doconut.NETFramework menampung penampil Doconut dalam aplikasi ASP.NET klasik pada .NET Framework 4.7.2 — IIS atau IIS Express, MVC 5 atau Web Forms. Penyiapan memiliki tiga bagian: paket NuGet, dua pendaftaran di Web.config, dan satu pemanggilan di Global.asax. Halaman ini mencakup ketiganya; Quick Start kemudian menempatkan dokumen pada sebuah halaman.

Persyaratan

• Proyek web menargetkan .NET Framework 4.7.2 atau yang lebih baru. Proyek 4.7 tidak dapat menggunakan paket ini; alihkan targetnya terlebih dahulu.
• Situs berjalan dalam integrated pipeline (default untuk pool aplikasi IIS dan IIS Express).

Halaman ini mencakup Doconut.NETFramework 26.9.0 dan selanjutnya. Versi 26.8.0 dan sebelumnya menargetkan .NET Framework 4.7 dengan API yang berbeda; jalur itu dihentikan. Memperbarui aplikasi yang ada melintasi batas tersebut dibahas di Migration.

Instal paket

Dari Package Manager Console:

Install-Package Doconut.NETFramework

Atau, dalam proyek bergaya SDK:

dotnet add package Doconut.NETFramework

Mesin rendering tertanam dalam paket: tidak ada assembly mesin terpisah yang perlu direferensikan, disalin, atau dideploy. Kapabilitas opsional dikirim sebagai paket masing‑masing — misalnya Doconut.NETFramework.Converter dan Doconut.NETFramework.Dicom — dan masing‑masing memerlukan lisensi yang memberikannya (lihat Plugin System).

Konfigurasi Web.config

Doconut melayani dua jenis permintaan, dan IIS mengarahkan keduanya melalui Web.config:

• DocImage.axd — halaman penampil, thumbnail, pencarian, dan endpoint anotasi, dilayani oleh Doconut.DocImageHandler.
• /doconut-res/* — skrip, stylesheet, dan ikon milik penampil, tertanam dalam assembly dan dilayani oleh Doconut.DoconutResourceModule.

Tambahkan keduanya, beserta pengaturan yang mereka bergantung pada:

<configuration>
  <system.web>
    <!-- MVC 5 saja: Razor mengompilasi tampilan pada waktu jalan dan membutuhkan facade netstandard. -->
    <compilation targetFramework="4.7.2">
      <assemblies>
        <add assembly="netstandard, Version=2.0.0.0, Culture=neutral, PublicKeyToken=cc7b13ffcd2ddd51" />
      </assemblies>
    </compilation>
    <!-- maxRequestLength dalam KILOBYTE: 200 MB. -->
    <httpRuntime targetFramework="4.7.2" maxRequestLength="204800" />
    <!-- Baca file .cshtml dan .aspx sebagai UTF-8, bukan sebagai halaman kode ANSI server. -->
    <globalization fileEncoding="utf-8" requestEncoding="utf-8" responseEncoding="utf-8" />
  </system.web>
  <system.webServer>
    <security>
      <requestFiltering>
        <!-- maxAllowedContentLength dalam BYTE: sama dengan 200 MB. -->
        <requestLimits maxAllowedContentLength="209715200" />
      </requestFiltering>
    </security>
    <modules runAllManagedModulesForAllRequests="true">
      <add name="DoconutResourceModule" type="Doconut.DoconutResourceModule, Doconut" />
    </modules>
    <handlers>
      <add name="DocImage" verb="GET,HEAD,POST" path="DocImage.axd"
           type="Doconut.DocImageHandler, Doconut" />
    </handlers>
  </system.webServer>
</configuration>

Setiap baris mencegah kegagalan yang tidak menghasilkan pengecualian:

• verb="GET,HEAD,POST" — pertahankan HEAD. Penampil mengirim permintaan HEAD untuk halaman 1 guna mendeteksi gambar animasi. Tanpa verb ini, IIS menjawab 404 sebelum handler dijalankan: dokumen tetap ditampilkan, tetapi deteksi animasi tidak pernah berfungsi dan konsol peramban dipenuhi 404.
• runAllManagedModulesForAllRequests="true" — /doconut-res/*.js, .css, dan .png terlihat seperti file statis, dan IIS akan menyerahkannya ke handler file statis sebelum modul sumber daya melihatnya. Hasilnya adalah penampil tanpa skrip atau ikon.
• <globalization fileEncoding="utf-8"> — file halaman yang disimpan sebagai UTF-8 tanpa byte-order mark akan dibaca dengan halaman kode ANSI server, sehingga setiap karakter non-ASCII sampai ke peramban dengan enkoding ganda (em dash muncul sebagai —). File tersebut benar di disk, dan halaman tetap mendeklarasikan <meta charset="utf-8">.
• Assembly netstandard (MVC 5) — Razor mengompilasi tampilan saat pertama diminta, dengan daftar referensi sendiri yang tidak menyertakan facade ini. Tampilan yang melakukan apa pun secara dinamis selain akses anggota sederhana akan gagal dengan CS0012 dan menghasilkan 500 kosong, dan hanya halaman yang memicu kegagalan yang terpengaruh. Kesalahan kompilasi muncul hanya di log peristiwa Windows (sumber ASP.NET). Aplikasi Web Forms tidak memerlukan baris ini.
• Batas unggahan — ASP.NET membaca seluruh isi permintaan sebelum handler apa pun dijalankan, sehingga unggahan yang melebihi batas ini ditolak oleh IIS dengan halaman kesalahan sendiri. Jaga agar maxRequestLength (kilobyte) dan maxAllowedContentLength (byte) selaras, dan di atas file terbesar yang dibuka atau diunggah pengguna Anda.

Dua pengaturan lagi penting, dan keduanya biasanya sudah benar:

• Status sesi tetap aktif. Secara default sebuah halaman hanya dilayani ke sesi ASP.NET yang membuka dokumen, jadi situs tidak boleh mengatur <sessionState mode="Off" />. Lihat Sessions & Security.
• Pengalihan binding. Pertahankan pengalihan binding <runtime> yang ditulis NuGet ke dalam Web.config. Pada proyek bergaya SDK, salin mereka dari bin\<YourApp>.dll.config yang dihasilkan, karena ASP.NET klasik hanya membaca pengalihan dari Web.config. Pengalihan yang menyebut versi yang tidak ada di bin\ menghentikan seluruh aplikasi dengan 500 kosong saat startup.

Daftarkan Doconut di Global.asax

Tidak ada builder dan tidak ada pipeline middleware di System.Web. Doconut disusun sekali per proses worker oleh DoconutHost.Initialize di Application_Start, dan dibebaskan oleh DoconutHost.Shutdown di Application_End:

// Global.asax.cs
protected void Application_Start()
{
    Doconut.DoconutHost.Initialize(options =>
    {
        options.LicensePath = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    });
}

protected void Application_End()
{
    Doconut.DoconutHost.Shutdown();
}

DoconutHost.Initialize membangun layanan yang digunakan oleh handler, modul sumber daya, dan kode Anda sendiri. Kode Anda mengaksesnya melalui DoconutHost.Services (lihat DoconutHost). Hanya panggilan pertama yang mengonfigurasi apa pun; panggilan kedua diabaikan. Pada aplikasi MVC, juga pastikan dua jalur Doconut tidak masuk ke routing — Quick Start menunjukkan Application_Start yang lengkap.

Semua opsi

DoconutOptions menerima properti yang dapat diatur berikut. Setiap properti bersifat opsional.

Ketika lebih dari satu sumber lisensi diatur, LicenseStream mengungguli LicenseContent, yang mengungguli LicensePath, yang mengungguli penemuan otomatis — lihat License Setup.

Doconut.DoconutHost.Initialize(options =>
{
    options.LicensePath     = HostingEnvironment.MapPath("~/wwwroot/Doconut.Viewer.lic");
    options.ResourcesPath   = "/doconut-res"; // tempat JS/CSS/gambar penampil disajikan
    options.UnsafeMode      = false;          // pertahankan keamanan sesi
    options.ShowDoconutInfo = false;
});
// Titik akhir halaman bukan opsi di sini: itu adalah handler DocImage.axd yang dideklarasikan di Web.config.

Langkah selanjutnya

• Panduan Cepat — buka dokumen dan render di peramban, dalam MVC 5 atau Web Forms.
• Pengaturan Lisensi — tempat Doconut mencari file lisensi Anda.