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 token dokumen melalui sumber daya atau middleware dari generasi lain.

Mengapa nama paket NuGet mungkin tidak memberi tahu Anda

Kedua generasi didistribusikan dengan ID paket Doconut.NET6. Referensi paket, file kunci, atau .nupkg yang di‑cache tidak mengidentifikasi API hosting secara otomatis. Catat versi paket yang tepat dan periksa Program.cs, konstruksi viewer, pembukaan dokumen, serta 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 ke 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 hidup 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 sama 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 menganggap 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.

Startup dan injeksi ketergantungan

Aplikasi klasik membangun Viewer dengan ketergantungan 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 ketergantungan:

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

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

Viewer adalah layanan transient. Manajer sesi dokumen dan cache‑nya memiliki status dokumen yang lebih lama, bukan instance Viewer yang di‑inject 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()));

Di 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 selaras.

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

Konstruksi dan masa hidup Viewer

Hapus cache milik aplikasi untuk objek Viewer. Inject Viewer ke 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 log, simpan, atau tempatkan di 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 cutover. Buka setiap dokumen kembali melalui API saat ini.

Kelas konfigurasi

API saat ini memisahkan kepentingan:

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

Toolbar Viewer, Pencarian, dan Anotasi

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

1. memancarkan CSS Viewer dan CSS Search/Annotation berlisensi dengan ReferenceCss;
2. merender toolbar Viewer milik aplikasi;
3. merender searchBarMount, annBarMount, dan mount Viewer yang diperlukan;
4. memancarkan skrip Viewer dan modul berlisensi dengan ReferenceScripts;
5. memuat viewerToolbar.js milik aplikasi;
6. menginisialisasi satu objViewer;
7. menginisialisasi Ribbon Search dan Annotation yang berlisensi;
8. memanggil attach(objViewer) pada setiap Ribbon;
9. membuka dokumen dan memanggil objViewer.View(token).

Pencarian dan Anotasi adalah modul yang terpasang pada Viewer yang sama, bukan toolbar independen. Toolbar utama milik aplikasi host; Ribbon Pencarian dan Anotasi adalah sumber daya yang disisipkan dan dikontrol oleh kapabilitas.

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

Registrasi plugin

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

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

AddDoconut() memvalidasi kapabilitas plugin yang terdaftar pada startup. Converter dan DICOM adalah plugin .NET 6 yang dirilis. Search dan Annotation standar adalah fitur berlisensi bawaan, bukan paket AddPlugin<TPlugin>().

Keamanan sesi dan dokumen

Integrasi saat ini mengikat dokumen ke token tak transparan dan sesi yang di‑cache. Dengan UnsafeMode = false secara default, UseDoconut() menambahkan keamanan akses dokumen dan host harus mengkonfigurasi 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 kedaluwarsa, dan token dari sesi browser yang berbeda.

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

Menguji migrasi

Setidaknya, verifikasi:

• startup aplikasi dengan lisensi produksi dan setiap plugin yang terdaftar;
• CSS/skrip Viewer dan semua permintaan gambar halaman di bawah jalur yang dipilih;
• pembukaan dokumen, navigasi, zoom, thumbnail, cetak, dan penutupan eksplisit;
• Pencarian pada dokumen berisi teks serta keadaan tidak dapat dicari pada file hanya gambar;
• muatan, penyimpanan, ekspor, dan gating kapabilitas Anotasi;
• penemuan target Converter, output, unduhan, dan keadaan 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;
• tampilan seluler, mode gelap, dan jalur reverse‑proxy produksi.

Rencana rollback

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

Sebelum cutover, dokumentasikan:

• slot deployment atau artefak yang digunakan untuk rollback;
• dampak basis data/cache, bila ada;
• bagaimana sesi dokumen aktif akan dibatalkan;
• health check dan dokumen smoke yang digunakan untuk memutuskan rollback;
• siapa yang dapat memulihkan set paket dan konfigurasi sebelumnya.

Dokumentasi legacy

Manual klasik yang diterjemahkan tetap tersedia di Pengaturan .NET 6 Legacy. Gerbang integrasi Gerbang integrasi Klasik 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.