Migrasi dari integrasi .NET 6 klasik

Doconut memiliki dua integrasi .NET 6 yang berbeda. Mereka dapat menggunakan nama paket Doconut.NET6 yang sama, jadi identifikasi generasi dari API dalam aplikasi sebelum mengubah paket, startup, lisensi, atau sumber daya browser.

Integrasi .NET 6 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.

Mengapa nama paket NuGet mungkin tidak memberi tahu Anda

Kedua generasi telah dirilis di bawah ID paket Doconut.NET6. Referensi paket, file lock, atau .nupkg yang di-cache oleh karena itu tidak mengidentifikasi API hosting secara sendiri. Catat versi paket yang tepat dan periksa Program.cs, konstruksi viewer, pembukaan dokumen, dan skrip browser secara bersamaan.

Rilis saat ini yang diaudit untuk panduan ini adalah Doconut.NET6 26.7.0. Paket publik opsionalnya adalah Doconut.NET6.Converter dan Doconut.NET6.Dicom, yang dipatok pada versi rilis yang sama dengan paket inti.

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 pemetaan DocImage.axd, pemanggilan new Viewer(...), pemanggilan pemuatan lisensi, skrip Doconut yang disalin, aksi toolbar khusus, dan endpoint pembukaan dokumen.
4. Pertahankan file .lic saat ini dan rahasia deployment di luar kontrol sumber.
5. Ambil kumpulan 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, routing permintaan, kepemilikan sesi, dan pengiriman sumber daya klien.

Kompatibilitas paket dan lisensi

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

dotnet add package Doconut.NET6

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

dotnet add package Doconut.NET6 --version 26.7.0

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

LicenseStream > LicenseContent > LicensePath > automatic discovery

Penemuan otomatis mencari file Doconut.Viewer.lic dan file pendamping Doconut.Viewer.<Capability>.lic. Panggilan klasik ke Viewer.DoconutLicense(...) atau Viewer.SetLicensePlugin(...) bukan mekanisme startup saat ini. Pindahkan lisensi ke DoconutOptions, pertahankan file pendamping bersama saat menggunakan penemuan otomatis, restart setelah mengubah lisensi, dan verifikasi kapabilitas melalui IDoconutLicenseService.

Jangan mengasumsikan 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.

Memulai dan injeksi dependensi

Aplikasi klasik membangun Viewer dengan dependensi cache ASP.NET dan request‑accessor:

// Classic integration — contrast only; do not compile this against the current SDK.
var viewer = new Viewer(_cache, _accessor, licenseFilePath);

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

builder.Services.AddDoconut(options =>
{
    options.LicensePath = "Doconut.Viewer.lic";
    options.UnsafeMode = false;
});
builder.Services.AddSession();

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

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

Middleware dan routing sumber daya

Hapus cabang MapWhen klasik yang mendeteksi DocImage.axd:

// Classic integration — remove during the cutover.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

Dalam pipeline saat ini:

1. panggil UseSession() sebelum Doconut sementara keamanan sesi diaktifkan;
2. panggil UseDoconutResources() sebelum UseDoconut();
3. pertahankan ResourcesPath, URL sumber daya yang dihasilkan, dan ResPath klien tetap selaras;
4. ketika memetakan UseDoconut() ke sebuah cabang, pertahankan cabang tersebut dan BasePath klien tetap selaras.

MiddlewarePath adalah konfigurasi yang divalidasi; ia tidak membuat cabang ASP.NET Core secara otomatis. Gunakan pipeline sederhana dalam contoh kompilasi di atas atau pengaturan eksplisit app.Map("/doconut", branch => branch.UseDoconut()) yang digunakan secara konsisten oleh klien.

Konstruksi dan masa pakai Viewer

Hapus cache milik aplikasi untuk objek Viewer. Suntikkan Viewer ke dalam endpoint, halaman Razor, controller, atau layanan aplikasi berskala:

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

Token yang dikembalikan mengidentifikasi sesi dokumen sisi server. Perlakukan sebagai kredensial bearer: jangan mencatatnya, menyimpannya, atau menempatkannya dalam analitik.

Membuka dan menutup dokumen

Ganti OpenDocument(...) sinkron dengan OpenDocumentAsync(...):

// Current .NET 6 integration: Viewer comes from DI and document opening is asynchronous.
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { AllowSearch = true });

Overload saat ini menerima jalur file atau stream, konfigurasi format opsional, DocOptions opsional, dan token pembatalan. Tutup sesi server secara eksplisit ketika browser tidak lagi membutuhkannya:

viewer.CloseDocument(token);

Jangan gunakan kembali token klasik setelah migrasi. Buka setiap dokumen lagi melalui API saat ini.

Kelas konfigurasi

API saat ini memisahkan kepentingan:

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

Toolbar Viewer, Search, dan Annotation

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

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

Search dan Annotation adalah modul yang terpasang pada Viewer yang sama, bukan toolbar independen. Toolbar utama milik aplikasi host; Ribbon Search dan Annotation tertanam, sebagai sumber daya yang dibatasi kemampuan.

Hapus file klasik 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.

Pendaftaran Plugin

Metode lisensi plugin statis klasik 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 6 yang dirilis. Pencarian Normal dan Anotasi adalah fitur berlisensi bawaan, bukan paket AddPlugin<TPlugin>().

Keamanan sesi dan dokumen

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

builder.Services.AddSession();
app.UseSession();

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

Aplikasi referensi Distributed menambahkan tiket akses dan detail transportasi. API tersebut tidak diperlukan untuk migrasi node tunggal normal.

Pengujian migrasi

Setidaknya, verifikasi:

• startup aplikasi dengan lisensi produksi dan setiap plugin yang terdaftar;
• CSS/script Viewer dan semua permintaan gambar‑halaman pada jalur yang dipilih;
• pembukaan dokumen, navigasi, zoom, thumbnail, pencetakan, dan penutupan eksplisit;
• Pencarian pada dokumen yang berisi teks dan keadaan tidak dapat dicari pada file hanya gambar;
• pemuatan, penyimpanan, ekspor Anotasi, dan pembatasan kemampuan;
• penemuan target Converter, output, unduhan, dan status watermark;
• halaman, frame, dan animasi DICOM; metadata teknis .NET 6 tidak tersedia;
• dokumen yang dilindungi kata sandi, font khusus, teks non‑Latin, dan batas waktu yang dikonfigurasi;
• penolakan token lintas sesi dan perilaku sesi kedaluwarsa;
• perangkat seluler, mode gelap, dan jalur reverse‑proxy produksi.

Rencana rollback

Pertahankan artefak penyebaran klasik, paket yang cocok, file lisensi, dan sumber daya peramban yang disalin bersama. Rollback yang aman mengganti seluruh generasi aplikasi; itu tidak mencampur server klasik dengan skrip saat ini atau server saat ini dengan panggilan DocImage.axd klasik.

Sebelum pemotongan, dokumentasikan:

• slot atau artefak penyebaran yang digunakan untuk rollback;
• dampak basis data/cache, bila ada;
• bagaimana sesi dokumen aktif akan dibatalkan;
• pemeriksaan kesehatan dan dokumen uji coba yang digunakan untuk memutuskan rollback;
• siapa yang dapat mengembalikan set paket dan konfigurasi sebelumnya.

Dokumentasi legacy

Manual klasik yang diterjemahkan tetap tersedia di Legacy .NET 6 setup. Panduan baru Classic integration gateway menjelaskan sinyal identifikasi yang sama dan menautkan kembali ke panduan migrasi ini.

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