Migrasi

Halaman ini membahas peningkatan aplikasi ASP.NET yang ada dari Doconut.NETFramework 26.8.0 atau lebih lama (.NET Framework 4.7) ke 26.9.0 dan selanjutnya (.NET Framework 4.7.2). Paket contoh Doconut menyertakan panduan migrasi lengkap dan contoh klasik yang dipindahkan ke API baru — MVC 5, web farm, dan Web Forms. Membandingkan aplikasi Anda dengan contoh asalnya adalah jalur tercepat.

Satu paket, dua versi

Kedua pustaka dipublikasikan dengan ID paket yang sama, Doconut.NETFramework. Versi membedakan keduanya:

Memperbarui paket adalah proses peningkatan. Tidak ada paket terpisah untuk diinstal dan tidak ada lapisan kompatibilitas: 26.9.0 memiliki permukaan API yang berbeda, jadi harapkan kesalahan kompilasi setelah pembaruan — sisanya ada di halaman ini. Jalur .NET Framework 4.7 dihentikan dan 26.8.0 adalah rilis terakhirnya. Anda dapat tetap menggunakannya — tidak ada perbaikan keamanan di sini yang akan Anda lewatkan — tetapi rilis baru, plugin, mode terdistribusi, dan widget drop‑in hanya tersedia pada 26.9.0 dan selanjutnya.

1. Menargetkan ulang dan memperbarui paket

Targetkan ulang proyek web ke .NET Framework 4.7.2 terlebih dahulu: proyek yang masih menargetkan 4.7 tidak dapat menginstal 26.9.0, dan NuGet menolak pembaruan. Kemudian perbarui Doconut.NETFramework dan tambahkan paket plugin yang Anda gunakan (Doconut.NETFramework.Converter, Doconut.NETFramework.Dicom, …). Setiap plugin memerlukan lisensi yang memberikannya.

Jika proyek menggunakan packages.config, pembaruan menjalankan langkah uninstall versi sebelumnya, yang menghapus handler DocImage dari Web.config, dan 26.9.0 tidak menambahkannya kembali. Daftarkan kembali seperti yang ditunjukkan pada langkah 3; sampai Anda melakukannya, DocImage.axd menjawab 404 dan tidak ada halaman yang ditampilkan.

2. Namespace: hampir semua dipindahkan ke root

Nama tipe tidak berubah: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, FileShareConfig dan sisanya semuanya masih ada. Pada kebanyakan file, seluruh perubahan hanyalah menghapus baris using.

3. Startup: DoconutHost.Initialize dan dua entri Web.config

Paket klasik membangun penampilnya per permintaan, dengan opsi sebagai properti dari instance tersebut. Paket baru memiliki composition root, dibangun sekali di Application_Start, dan penampil adalah layanan yang Anda resolusi:

// Sebelum - Doconut.NETFramework 26.8.0 dan sebelumnya, atas permintaan
var viewer = new Viewer
{
    ID = "ctlDoc",
    IncludeJQuery = true,
    BasePath = "/",
    FitType = "width"
};

// Doconut.NETFramework 26.9.0+ - Viewer diresolusikan dari DoconutHost, lisensi dikonfigurasi sekali di DoconutHost.Initialize()
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
var token  = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

DoconutHost.Initialize masuk ke Application_Start dan DoconutHost.Shutdown di Application_End, dan Web.config memperoleh handler DocImage.axd serta modul sumber daya — keduanya ada di Instalasi. Pengaturan tampilan per halaman (FitType, FixedZoom, ShowHyperlinks, …) dipindahkan dari instance penampil ke opsi widget, atau ke ViewerConfig yang diteruskan ke Viewer.RenderViewer (lihat ViewerConfig). new Viewer() tetap dapat dikompilasi setelah DoconutHost.Initialize dijalankan, sehingga kode-behind yang dimigrasikan dapat mempertahankan baris itu sambil Anda memindahkan pengaturannya.

Keamanan berfungsi seperti sebelumnya. Membuka dokumen memberikan sesi ASP.NET saat ini akses ke halamannya, dan DocImage.axd menolak semua orang lain. Pengaturan aplikasi DoconutUnSafeMode yang menonaktifkan ini kini menjadi options.UnsafeMode di DoconutHost.Initialize — biarkan tetap false. Lihat Sesi & Keamanan.

Kegagalan startup yang membuat seluruh situs turun. Plugin terdaftar yang kemampuannya tidak diberikan lisensi melemparkan di Application_Start, dan aplikasi kemudian menjawab 500 kosong untuk setiap permintaan — tidak ada halaman error, tidak ada apa pun di log IIS, hanya entri di log peristiwa Windows (sumber ASP.NET). Lisensi dibaca dari wwwroot di bawah root situs dan tidak di tempat lain, dan Doconut.Viewer.lic dasar harus ada atau lisensi plugin di sampingnya tidak dibaca. Lihat Pengaturan Lisensi.

4. Farm web: dari bendera ke mode terdistribusi

Model klasik adalah viewer.IsWebfarm = true plus ExportToPng(path). Model baru didaftarkan sekali: setiap node berbagi satu store dan satu kunci penandatangan, dan tiket yang ditandatangani yang terikat pada browser menggantikan "node mana pun yang menjawab":

Doconut.DoconutHost.Initialize(
    options => options.UnsafeMode = false,
    services => services.AddDoconutDistributed(d =>
    {
        d.Store             = CloudLocation.FileShare;
        d.FileShareRootPath = @"\\fileserver\doconut-shared";   // WebfarmPath adalah alias
        d.SigningKey        = farmKey;                           // >= 32 byte, sama pada setiap node
    }));

Kemudian buka dokumen secara normal, mengikat browser (DocOptions.BrowserId = DoconutFarmBinding.EnsureBrowserId(...)) dan memberikan viewer.AccessToken ke widget dengan token. Sesi & Keamanan(Sesi & Keamanan) memiliki langkah‑langkahnya; contoh web‑farm adalah node lengkap. IsWebfarm dan WebfarmPath masih dapat dikompilasi, tetapi mereka tidak lagi mengaktifkan apa pun.

Dua hal yang tampak seperti keberhasilan tetapi tidak: DistributedDocumentPublisher.PublishAsync menulis file yang dirender dari dokumen tetapi tidak membuka sesi, sehingga penampil yang diarahkan ke token yang dipublikasikan mendapatkan gambar error ~2 KB dengan status 200; dan klien uji tanpa cookie doconut-client mendapatkan gambar yang sama, bukan 401. Bedakan halaman nyata dari gambar error berdasarkan ukuran.

5. Konversi adalah plugin, dan jauh lebih kecil

Enum SourceFormatConverter, dua belas kelas *ConfigConverter, dan enum target bersarang mereka digantikan oleh satu enum, ConversionTarget, dan satu pemanggilan:

using System.IO;
using System.Threading;
using Doconut;
using Doconut.Configs.Conversion;

// Anggap DoconutHost sudah diinisialisasi dan CancellationToken bernama ct tersedia.
var provider = DoconutHost.Services;
var converter = (DocumentConverter)provider.GetService(typeof(DocumentConverter));
Stream source = /* stream input Anda */;
var result = await converter.ConvertAsync(source, ".dwg", ConversionTarget.Pdf, null, ct);

Format sumber berasal dari ekstensi yang Anda berikan. Tidak ada shim kompatibilitas: setiap referensi SourceFormatConverter adalah kesalahan kompilasi yang Anda selesaikan dengan menghapusnya. Objek opsi per‑format tidak bertahan — WordConfigConverter.HtmlOptions dan CadConfigConverter.CadOptions.ShowColor tidak memiliki padanan melalui ConvertAsync. Di Web Forms, jangan pernah memblokir pada ConvertAsync — lihat Plugin Konverter(Plugin Konverter).

6. Penyimpanan cloud: capai sebagai folder bersama

Tipe konfigurasi cloud dipindahkan ke Doconut.Clouds tanpa perubahan. Penangan permintaan cloud, bagaimanapun, adalah komponen ASP.NET Core, dan aplikasi klasik tidak memiliki pipeline untuk menjalankannya. Dari situs System.Web, capai penyimpanan cloud sebagai folder bersama — di Azure, sebuah Azure Files share yang dipasang pada setiap node — diakses melalui FileShareConfig.

7. Perubahan sisi klien yang gagal diam‑diam

Setiap item di bawah ini dapat dikompilasi, dijalankan, tidak mencatat apa pun, dan melakukan hal yang salah:

Tiga lagi: penampil tidak menggambar toolbarnya sendiri (halaman Anda menghubungkan Zoom, Next, GotoPage dan sisanya ke tombolnya sendiri); penampil yang dibuat di dalam modal Bootstrap tersembunyi berukuran 0×0 dan tidak menggambar apa pun sampai Anda memberi kontainernya tinggi eksplisit dan menyesuaikannya kembali pada shown.bs.modal; dan AllowSearch default ke false untuk PDF, sehingga dokumen dirender dengan sempurna sementara setiap pencarian tidak menghasilkan apa pun.

8. Apa yang menghilang

Urutan kerja yang disarankan

1. Alihkan target, ganti paket, dan buat Global.asax dikompilasi dengan DoconutHost.Initialize serta dua pendaftaran Web.config. Situs harus mulai.
2. Satu halaman penampil: dapatkan dokumen untuk dirender, lalu kerjakan bagian 7 sampai bilah alat, pencarian, dan anotasi berfungsi. Verifikasi di peramban nyata — tidak ada yang di bagian itu menghasilkan kesalahan.
3. Konversi (bagian 5): mekanis, dan sebagian besar kesalahan kompilasi.
4. Halaman yang tersisa, menggunakan contoh yang dipindahkan sebagai target perbedaan.
5. Web farm (bagian 4), jika Anda memiliki satu. Uji dengan dua node dan peramban, atau klien yang menyimpan cookie.