Migrasi ke .NET Standard 2.1

Doconut memiliki dua integrasi .NET Standard yang berbeda. Mereka menggunakan nama paket Doconut.NETStandard yang sama, jadi identifikasi generasi dari versi dan API dalam aplikasi sebelum mengubah paket, startup, lisensi, atau sumber daya peramban.

Versi adalah percabangan di jalan

Kedua generasi dipublikasikan di bawah ID paket yang sama. Hanya versi yang membedakan keduanya:

Meningkatkan nomor versi adalah peningkatan. Tidak ada paket terpisah untuk diinstal dan tidak ada shim kompatibilitas — 26.8.0 memiliki permukaan API yang berbeda. Harapkan kesalahan kompilasi setelah peningkatan; sisanya dari panduan ini adalah daftar kesalahan tersebut.

Integrasi mana yang Anda gunakan?

Jika kedua kolom muncul dalam aplikasi yang sama, anggap migrasi tidak lengkap. Jangan mengirim satu token dokumen melalui sumber daya atau middleware dari generasi lain.

Periksa kerangka kerja host terlebih dahulu

Ini adalah gerbang keras, bukan preferensi. Paket saat ini menargetkan netstandard2.1:

.NET Framework tidak dapat merujuk ke pustaka netstandard2.1. Jika aplikasi berjalan di .NET Framework, berhenti di sini dan gunakan paket Doconut.NETFramework sebagai gantinya; mulai dari 26.9.0 ia memerlukan .NET Framework 4.7.2. Kedua aplikasi referensi untuk rilis ini menargetkan net8.0.

Sebelum Anda melakukan migrasi

1. Buat cabang dan cadangan yang dapat dideploy dari aplikasi yang ada.
2. Catat versi paket inti dan plugin yang tepat.
3. Inventarisasi setiap pemanggilan new Viewer(...), pemanggilan InitCache(), pemanggilan pemuatan lisensi, pemetaan UseDoconutWebFarm, kontroler konversi, skrip Doconut yang disalin, aksi toolbar kustom, callback viewer, dan endpoint pembukaan dokumen.
4. Pertahankan file .lic saat ini dan rahasia deployment di luar kontrol sumber.
5. Ambil sekumpulan representatif dokumen PDF, Office, gambar, CAD, email, DICOM, yang dapat dicari, dilindungi kata sandi, dan beranotasi.
6. Catat batas waktu sesi yang ada, perilaku keamanan, font, dan pengaturan platform.

Migrasikan satu lingkungan sebelum mengubah produksi. Integrasi saat ini mengubah masa pakai layanan, perutean permintaan, kepemilikan sesi, pengiriman sumber daya klien, dan — jika Anda menjalankan farm — cara halaman mencapai peramban secara keseluruhan.

1. Namespace: hampir semua dipindahkan ke root

Tipe konfigurasi tersebar di empat namespace. Sekarang semuanya berada di Doconut.

Nama tipe tidak berubah: WordConfig, PdfConfig, ExcelConfig, CssConfig, ScriptConfig, CloudUploadConfig, AzureConfig, CDNConfig, FileShareConfig dan sisanya semuanya masih ada. Di sebagian besar file, seluruh edit adalah menghapus dua baris using.

Doconut.Configs.Editor (BaseConfigEditor, PdfConfigEditor) telah dihapus dan tidak memiliki pengganti dalam paket ini. Jika aplikasi Anda merujuk ke tipe tersebut, rencanakan bagian itu secara terpisah dan jangan menganggapnya sebagai bagian dari migrasi ini.

2. Kompatibilitas paket dan lisensi

Ganti atau perbarui paket inti secara sengaja; jangan bergantung pada ID paket yang identik untuk memilih API baru. Perintah default menginstal rilis stabil terbaru:

dotnet add package Doconut.NETStandard

Untuk migrasi yang dapat direproduksi ke rilis yang diaudit oleh panduan ini, berikan versi sebagai opsi terpisah:

dotnet add package Doconut.NETStandard --version 26.8.0

Pertahankan setiap plugin Doconut pada versi yang sama dengan paket inti — Doconut.NETStandard.Converter dan Doconut.NETStandard.Dicom. Integrasi saat ini memuat lisensi sekali selama AddDoconut(), menggunakan prioritas ini:

LicenseStream > LicenseContent > LicensePath > automatic discovery

Penemuan otomatis mencari Doconut.Viewer.lic dan file pendamping Doconut.Viewer.<Capability>.lic. Panggilan statis sebelumnya Viewer.DoconutLicense(...) dan Viewer.SetLicensePlugin(...) bukanlah mekanisme startup saat ini, dan begitu juga List<string> dari jalur lisensi yang diterima oleh konstruktor lama Viewer. Pindahkan lisensi ke DoconutOptions, pertahankan file pendamping bersama saat menggunakan penemuan otomatis, restart setelah mengubah lisensi, dan verifikasi kemampuan melalui IDoconutLicenseService.

Jangan menganggap bahwa keberadaan lisensi plugin lama membuktikan hak untuk build plugin saat ini. Uji Viewer, Search, Annotation, Converter, dan DICOM secara terpisah dengan artefak rilis yang disetujui.

3. Startup dan injeksi dependensi

Sebelumnya penampil dibangun per permintaan dan opsi diteruskan ke middleware:

// Integrasi sebelumnya — hanya untuk perbandingan; jangan mengompilasi ini terhadap SDK saat ini.
var viewer = new Viewer(_cache, _accessor);
// …
appBranch.UseDoconut(new DoconutOptions { UnSafeMode = false, ShowDoconutInfo = false });

Integrasi saat ini mendaftarkan Doconut sekali dan menerima Viewer dari injeksi dependensi:

builder.Services.AddDoconut(options =>
{
    options.UnsafeMode      = false;   // catat perubahan ejaan: UnSafeMode → UnsafeMode
    options.ShowDoconutInfo = false;
    options.LicensePath     = "Doconut.Viewer.lic";
});
builder.Services.AddDistributedMemoryCache(); // session state membutuhkan cache (MVC/Razor Pages sudah menambah satu)
builder.Services.AddSession();

app.UseSession();
app.UseDoconutResources();
app.UseDoconut();

Viewer adalah layanan transien. Manajer sesi dokumen dan cache-nya memiliki keadaan dokumen yang bertahan lebih lama, bukan instance Viewer yang disuntikkan secara khusus.

Tiga hal yang harus dipertahankan:

• new Viewer(cache, accessor) sudah tidak ada. Suntikkan Doconut.Viewer ke dalam controller Anda, atau gunakan @inject Doconut.Viewer Viewer dalam tampilan Razor.
• UseDoconutResources() menggantikan penulisan manual app.UseMiddleware<EmbeddedResourceMiddleware>(), dan harus dijalankan sebelum cabang dokumen.
• UnSafeMode → UnsafeMode. Penggantian satu karakter yang akan ditangkap oleh kompiler.

Ketika UnsafeMode adalah false, SDK memvalidasi token sesi terhadap permintaan asal, sehingga AddSession() / UseSession() masih harus berada dalam pipeline, UseSession() sebelum cabang.

Metode yang tidak lagi ada

4. Middleware dan routing sumber daya

UseDoconut() sekarang tidak mengambil argumen. Bentuk cabang MapWhen sendiri tidak perlu diubah — hanya middleware di dalamnya:

app.UseDoconutResources();   // SEBELUM cabang

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconut());

Dalam pipeline saat ini:

1. Panggil UseSession() sebelum Doconut saat keamanan sesi diaktifkan;
2. Panggil UseDoconutResources() sebelum UseDoconut();
3. Pertahankan ResourcesPath, URL sumber daya yang dihasilkan, dan client ResPath selaras;
4. Pertahankan cabang yang Anda petakan dan client BasePath selaras.

MiddlewarePath adalah konfigurasi yang divalidasi; ia tidak membuat cabang ASP.NET Core secara mandiri.

5. Konstruksi dan masa pakai Viewer

Remove application-owned caches of Viewer objects. There is nothing left in a Viewer worth holding on to: it carries no document state, and the session cache owns everything that outlives a request. Inject it into an endpoint, Razor page, controller, or scoped application service:

app.MapPost("/api/open", async (Viewer viewer) =>
{
    var token = await viewer.OpenDocumentAsync("wwwroot/files/Sample.pdf");
    return Results.Ok(new { token });
});

The returned token identifies a server-side document session. Treat it as a bearer credential: do not log it, persist it, or place it in analytics.

6. Membuka dan menutup dokumen

Replace synchronous OpenDocument(...) with OpenDocumentAsync(...):

// Integrasi saat ini: Viewer berasal dari DI dan pembukaan dokumen bersifat asinkron.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Current overloads accept a file path or stream, an optional format config, optional DocOptions, and a cancellation token. Close the server session explicitly when the browser no longer needs it:

viewer.CloseDocument(token);

Delete any InitCache() call and the flag guarding it — there is nothing to warm up by hand. Do not reuse a token minted by the previous library after the cutover: open each document again through the current API.

7. Web farm → terdistribusi: perubahan terbesar

UseDoconutWebFarm dan WebFarmOptions tidak ada lagi. Jika aplikasi Anda memanggilnya, bagian ini adalah peningkatan Anda; jika tidak, lewati ke §8.

Sebelumnya satu middleware melakukan semuanya: ia menyajikan gambar yang telah dipra-render dari folder bersama, dan memeriksa sementara node lain masih menulisnya.

// Integrasi sebelumnya — satu panggilan, koordinasi implisit melalui sistem berkas.
appBranch.UseDoconutWebFarm(new WebFarmOptions
{
    Path                = Path.Combine(env.WebRootPath, "webfarm"),
    PageWaitTimeSeconds = 180,
    StartWaitFromPage   = 5,
});

Pekerjaan yang sama sekarang dibagi menjadi dua bagian eksplisit. Sisi penulisan — node yang membuka dokumen memublikasikan seluruh set artefak (halaman, info dokumen, indeks pencarian, metadata) ke dalam share:

var result = await _publisher.PublishAsync(          // DistributedDocumentPublisher, disuntikkan dari DI
    pathToFile,
    new FileShareConfig
    {
        Location              = CloudLocation.FileShare,
        RootPath              = @"\\fileserver\doconut",   // folder yang sama yang Anda gunakan hari ini
        UsePerTokenSubfolders = true,
    },
    config,
    documentOptions,
    new DistributedDocumentPublishOptions
    {
        CleanUpStagingDirectory = true,
        FirstPagePriority       = true,
    });

return Content(result.Token);

Sisi pembacaan — setiap node melayani dari share:

app.MapWhen(
    ctx => ctx.Request.Path.Value?.EndsWith("DocImage.axd", StringComparison.OrdinalIgnoreCase) == true,
    branch => branch.UseDoconutCloud<FileShareCloudHandler>(options =>
    {
        options.Location          = CloudLocation.FileShare;
        options.CloudUploadConfig = /* FileShareConfig SAME seperti di atas */;
    }, "/"));

Topologi Anda tidak berubah. Arahkan RootPath ke share UNC yang sama dan setiap node tetap berfungsi seperti hari ini. Yang berubah adalah bahwa publikasi menjadi operasi yang Anda panggil, bukan efek samping dari rendering.

Kedua sisi harus setuju. Jika RootPath atau UsePerTokenSubfolders berbeda antara penerbit dan penangan, node lain akan menjawab 404. Bangun konfigurasi dalam satu pembantu dan panggil dari kedua sisi.

PageWaitTimeSeconds = 180 berarti "memblokir hingga tiga menit berharap halaman muncul". Penggantiannya eksplisit: dengan FirstPagePriority = true, halaman 1 dapat disajikan segera dan halaman berikutnya menjawab HTTP 202 Accepted sampai ditulis. Viewer yang terbundel secara otomatis mencoba kembali ketika retryOn409 diatur. Klien yang tidak mencoba kembali akan menampilkan ubin rusak untuk halaman yang masih dirender.

Pengaturan lengkap, termasuk publikasi latar belakang dan tiket akses, ada di Penyebaran Terdistribusi.

8. Konversi adalah plugin, dan jauh lebih kecil

Daftarkan plugin, lalu sisipkan facade DocumentConverter:

builder.Services.AddDoconut(o => o.AddPlugin<ConverterPlugin>());

// Integrasi sebelumnya
var converter = viewer.Converter.GetConverter();
var config    = new WordConfigConverter { TargetFormat = WordConfigConverter.EnTargetFormat.PDF };
var result    = converter.Convert(stream, SourceFormatConverter.DOCX, config);

// Integrasi saat ini
var result = await _converter.ConvertAsync(stream, ".docx", ConversionTarget.Pdf, null, ct);

Apa yang digantikan:

• SourceFormatConverter — hilang. Berikan ekstensi file sebagai string, termasuk titik.
• Tipe *ConfigConverter per keluarga (WordConfigConverter, ExcelConfigConverter, …), masing-masing dengan enum EnTargetFormat bersarang — hilang. Sekarang ada satu enum ConversionTarget untuk setiap keluarga.
• viewer.Converter.GetConverter() — hilang. Sisipkan Doconut.DocumentConverter.

ConvertAsync mengembalikan aliran yang dapat dicari, sehingga return File(result, mime, name) bekerja langsung — menyalin kode lama yang diperlukan oleh MemoryStream tidak diperlukan. Dalam contoh yang dikirim, ini menghapus sebuah switch ekstensi dengan 68 kasus dan sepuluh kontroler yang hampir identik.

Lihat Plugin Konverter untuk seluruh permukaannya.

9. Penyedia cloud

UseDoconutCloud menjadi generik. Penyedia adalah argumen tipe alih-alih nilai Location yang dipilih di dalam middleware:

// Integrasi sebelumnya
appBranch.UseDoconutCloud(new CloudOptions { Location = CloudLocation.CDN, ... });

// Integrasi saat ini
branch.UseDoconutCloud<CDNCloudHandler>(options =>
{
    options.Location          = CloudLocation.CDN;
    options.CloudUploadConfig = new CDNConfig { DoconutCdnUrl = "..." };
}, "/");

Kelas konfigurasi tidak berubah kecuali namespace (Doconut.Configs.Cloud → Doconut.Clouds): AzureConfig, AmazonConfig, GoogleCloudConfig, DropBoxConfig, RedisConfig, CDNConfig, FTPConfig, plus FileShareConfig yang baru. Penangan dinamai <Provider>CloudHandler.

Penangan CDN bersifat hanya-baca — ia menyajikan apa yang sudah ada di CDN; tidak mengunggah apa pun.

10. Objek konfigurasi yang berganti nama

DocOptions juga memperoleh IsSecured.

API saat ini juga memisahkan kepedulian lebih ketat dibandingkan yang sebelumnya, jadi periksa bahwa setiap pengaturan berada pada objek yang kini memilikinya:

Jangan bawa DocOptions.ImageResolution ke depan sebagai kontrol rendering. Itu usang; atur BaseConfig.ImageResolution pada konfigurasi spesifik format. Tinjau semua default alih-alih mengasumsikan konfigurasi sebelumnya memiliki perilaku yang sama.

11. Penampil sisi klien — dua perubahan yang gagal SENYAP

Kedua hal ini membuat server berfungsi dengan sempurna. Dokumen Anda dirender, halaman terlihat benar, dan tidak ada yang muncul di konsol peramban. Baca bagian ini bahkan jika C# Anda berhasil dikompilasi pada percobaan pertama.

Callback penampil kini menjadi opsi, bukan fungsi global

Penampil sebelumnya memanggil penangan Anda dengan nama, menghasilkan nama fungsi global dari id kontainer. Mendeklarasikan function ctlDoc_OnViewerReady() pada halaman dengan <div id="div_ctlDoc"> sudah cukup. Penampil saat ini mengambil callback eksplisit dalam objek opsi dan tidak lagi mencari global tersebut:

objctlDoc = $("#div_ctlDoc").docViewer({
    // ... opsi Anda yang ada ...
    onViewerBusy:     ctlDoc_OnViewerBusy,      // ditemukan berdasarkan nama
    onViewerReady:    ctlDoc_OnViewerReady,     // ditemukan berdasarkan nama
    onCopy:           ctlDoc_Copy,              // adalah ctlDoc_Copy(text)
    onAutoLoadStatus: ctlDoc_AutoLoadStatus     // adalah ctlDoc_AutoLoadStatus(page)
});

Mengapa ini menjengkelkan: panggilan lama dibungkus dalam catch kosong, yang menelan semuanya. Sekarang fungsi Anda tidak pernah dijalankan dan tidak ada yang melaporkan kesalahan. Gejala biasanya adalah spinner yang terus berputar — karena fungsi yang menyembunyikannya adalah ctlDoc_OnViewerReady. Dokumen di belakangnya baik-baik saja.

Daftar opsi lengkapnya adalah onPageLoading, onPageLoaded, onThumbnailClicked, onPageClicked, onDoubleClick, onViewerBusy, onViewerReady, onViewerError, onCopy, onAnnSaved, onAnnSaveError, onAnnLoaded, onAnnClosed, onAutoLoadStatus, onThumbsShown, dan onError. Tidak ada callback klik tautan: penanganan hyperlink sudah terintegrasi, dipicu oleh showHyperlinks.

ResPath harus mengarah ke awalan sumber daya

ResPath: '',                      // SEBELUM — sumber daya berasal dari root aplikasi
ResPath: 'doconut-res/images',    // SEKARANG    — prefiks UseDoconutResources() dipasang

Jika Anda mengubah awalan melalui DoconutOptions.ResourcesPath, gunakan nilai itu sebagai gantinya.

12. Toolbar Penampil, Pencarian, dan Anotasi

Jangan migrasikan skrip lama satu per satu. Aplikasi referensi saat ini menyusun satu
paket halaman lengkap:

1. hasilkan CSS Penampil dan CSS Pencarian/Anotasi berlisensi dengan ReferenceCss;
2. render toolbar Penampil milik aplikasi;
3. render searchBarMount, annBarMount, dan mount Penampil yang diperlukan;
4. hasilkan skrip Penampil dan modul berlisensi dengan ReferenceScripts;
5. muat skrip pembantu toolbar milik aplikasi;
6. inisialisasi satu objViewer;
7. inisialisasi Ribbon Pencarian dan Anotasi berlisensi;
8. panggil attach(objViewer) pada setiap Ribbon;
9. buka dokumen dan panggil objViewer.View(token).

Pencarian dan Anotasi adalah modul yang terpasang pada Penampil yang sama, bukan toolbar independen.
Toolbar utama milik aplikasi host; Ribbon Pencarian dan Anotasi
tersemat, sumber daya yang dibatasi kemampuan.

Hapus file yang disalin secara manual seperti documentLinks.js dan docViewer.UI.js hanya setelah
halaman saat ini berfungsi dengan sumber daya yang dihasilkan oleh ReferenceCss dan ReferenceScripts.

13. Pendaftaran Plugin

Metode lisensi plugin statis tidak mendaftarkan plugin saat ini. Instal dan daftarkan setiap
paket yang dirilis secara eksplisit:

builder.Services.AddDoconut(options =>
{
    options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>();
    options.AddPlugin<Doconut.Plugins.Dicom.DicomPlugin>();
});

AddDoconut() memvalidasi kemampuan plugin yang terdaftar saat startup. Converter dan DICOM
adalah plugin .NET Standard yang dirilis. Pencarian dan Anotasi Normal adalah fitur berlisensi bawaan,
bukan paket AddPlugin<TPlugin>().

14. Keamanan Sesi dan Dokumen

Integrasi saat ini mengikat dokumen ke token opak dan sesi yang di‑cache. Dengan
UnsafeMode = false default, UseDoconut() menambahkan keamanan akses dokumen dan host
harus mengonfigurasi sesi ASP.NET:

builder.Services.AddDistributedMemoryCache(); // status sesi membutuhkan cache (MVC/Razor Pages sudah menambahkan satu)
builder.Services.AddSession();
app.UseSession();

Pertahankan DocOptions.IsSecured = true kecuali desain yang ditinjau memerlukan sebaliknya. Jangan pernah gunakan
UnsafeMode = true sebagai jalan pintas migrasi pada satu node. Uji permintaan tanpa token,
token yang rusak, token yang kedaluwarsa, dan token dari sesi peramban yang berbeda.

Di sebuah farm, permintaan halaman dapat mendarat pada node yang tidak pernah melihat permintaan pembukaan, sehingga
pemeriksaan per‑sesi akan menolaknya. Itu adalah satu-satunya kasus di mana UnsafeMode = true
benar — dan harus dipasangkan dengan tiket akses yang ditandatangani melalui
AddDoconutDistributedDocumentSecurity, tidak dikirim sendiri. Lihat
Penyebaran Terdistribusi.

Catatan Penamaan

Di semua kerangka kerja kelasnya adalah Viewer. Jika Anda menemukan DocumentViewer dalam potongan kode lama
atau artikel pihak ketiga, tipe itu tidak pernah ada di SDK.

15. Urutan Kerja yang Disarankan

1. Pastikan kerangka kerja host dapat mengonsumsi netstandard2.1. Jika tidak, hentikan.
2. Naikkan paket ke 26.8.0 dan bangun. Kerjakan kesalahan kompilasi — kebanyakan adalah
   baris using di §1.
3. Pindahkan startup ke AddDoconut() dan panggilan middleware ke urutan baru mereka (§3, §4).
4. Suntikkan Viewer di tempat Anda membangunnya, buat OpenDocument async, dan hapus
   InitCache() (§5, §6).
5. Jika Anda menggunakan web farm, lakukan §7 — satu-satunya bagian yang merupakan redesain bukan penggantian nama.
6. Jika Anda mengonversi dokumen, lakukan §8.
7. Lakukan §11 — perubahan sisi klien. Mereka adalah yang tidak akan mengumumkan diri.
8. Buka dokumen nyata di peramban, dan perhatikan spinner sibuk. Sebuah build hijau tidak membuktikan
   apa-apa di sini: lisensi, pendaftaran plugin, jalur sumber daya, dan callback penampil
   semua gagal hanya pada waktu berjalan. Untuk sebuah farm, verifikasi bahwa dokumen yang dipublikasikan oleh satu
   node dilayani oleh node lain.

Menguji migrasi

Setidaknya, verifikasi:

• memulai aplikasi dengan lisensi produksi dan setiap plugin yang terdaftar;
• CSS/script Viewer dan semua permintaan gambar halaman di bawah jalur yang dipilih;
• pembukaan dokumen, navigasi, zoom, thumbnail, cetak, dan penutupan eksplisit;
• Pencarian pada dokumen yang berisi teks dan keadaan tidak dapat dicari pada file hanya gambar;
• memuat anotasi, menyimpan, mengekspor, dan pembatasan kemampuan;
• penemuan target konverter, output, unduhan, dan keadaan watermark;
• halaman DICOM, frame, dan animasi; metadata teknis tidak tersedia pada paket ini;
• dokumen yang dilindungi kata sandi, font khusus, teks non-Latin, dan batas waktu yang dikonfigurasi;
• penolakan token lintas sesi dan perilaku sesi kedaluwarsa;
• untuk farm: publikasikan pada satu node, minta halaman terlambat dari node lain, dan konfirmasi bahwa viewer mencoba kembali respons 202 alih-alih menampilkan ubin yang rusak;
• mobile, mode gelap, dan jalur reverse-proxy produksi.

Rencana rollback

Pertahankan artefak penyebaran sebelumnya, paket yang cocok, file lisensi, dan sumber daya browser yang disalin bersama-sama. Rollback yang aman mengganti seluruh generasi aplikasi; itu tidak mencampur server generasi sebelumnya dengan skrip saat ini, atau server saat ini dengan situs panggilan new Viewer(...).

Sebelum pemindahan, dokumentasikan:

• slot penyebaran atau artefak yang digunakan untuk rollback;
• dampak penyimpanan bersama, jika ada — artefak yang dipublikasikan oleh 26.8.0 tidak dikonsumsi oleh middleware web-farm sebelumnya;
• bagaimana sesi dokumen aktif akan dibatalkan;
• pemeriksaan kesehatan dan dokumen uji coba yang digunakan untuk memutuskan rollback;
• siapa yang dapat memulihkan set paket dan konfigurasi sebelumnya.

Dokumentasi Legacy

Manual sebelumnya yang telah diterjemahkan tetap tersedia di Pengaturan .NET Standard Legacy. Gateway integrasi sebelumnya menjelaskan sinyal identifikasi yang sama dan menautkan kembali ke panduan migrasi ini.

Pertahankan URL historis dalam bookmark dan tiket dukungan selama instalasi netstandard2.0 masih ada. Itu mendokumentasikan generasi yang berbeda dan tidak diarahkan ke API saat ini.