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 generasinya dari API di 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 belum selesai. Jangan mengirim token dokumen melalui sumber daya atau middleware dari generasi lain.

Mengapa nama paket NuGet mungkin tidak memberi tahu Anda

Kedua generasi dipublikasikan dengan ID paket Doconut.NET6. Referensi paket, file kunci, atau .nupkg yang di‑cache oleh karena itu 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 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 kustom, dan endpoint pembukaan dokumen.
4. Pertahankan file .lic saat ini dan rahasia deployment di luar kontrol sumber.
5. Ambil sekumpulan contoh 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 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. Pemanggilan 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 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.

Memulai dan injeksi dependensi

Aplikasi klasik membuat Viewer dengan dependensi cache ASP.NET dan request-accessor:

// Integrasi klasik — hanya untuk perbandingan; jangan mengompilasi ini dengan SDK saat ini.
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.AddDistributedMemoryCache();
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.

Middleware dan routing sumber daya

Hapus cabang MapWhen klasik yang mendeteksi DocImage.axd:

// Integrasi klasik — hapus selama proses migrasi.
app.MapWhen(
    context => context.Request.Path.ToString().EndsWith("DocImage.axd"),
    branch => branch.UseDoconut(new DoconutOptions()));

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 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 konsisten digunakan 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 di sisi server. Perlakukan sebagai kredensial bearer: jangan mencatatnya, menyimpannya, atau menempatkannya dalam analitik.

Membuka dan menutup dokumen

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

// Integrasi .NET 6 saat ini: Viewer berasal dari DI dan pembukaan dokumen bersifat asinkron.
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 meneruskan DocOptions.ImageResolution sebagai kontrol rendering. Itu sudah usang; setel BaseConfig.ImageResolution pada konfigurasi spesifik format. Tinjau semua 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. 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 Anotasi 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 tersemat, 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 opak dan sesi yang di-cache. Dengan UnsafeMode = false secara default, UseDoconut() menambahkan keamanan akses dokumen dan host harus mengonfigurasi sesi ASP.NET:

builder.Services.AddDistributedMemoryCache(); // status sesi membutuhkan cache (MVC/Razor Pages sudah menambahkannya)
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 browser yang berbeda.

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

Menguji Migrasi

Setidaknya, verifikasi:

• pembukaan aplikasi dengan lisensi produksi dan setiap plugin yang terdaftar;
• CSS/script Viewer dan semua permintaan halaman-gambar 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 yang hanya berupa gambar;
• muat, simpan, ekspor Anotasi, dan pengaturan kemampuan;
• 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;
• mobile, mode gelap, dan jalur reverse-proxy produksi.

Rencana Rollback

Pertahankan artefak penyebaran klasik, paket yang cocok, file lisensi, dan sumber daya browser 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, jika ada;
• 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 Warisan

Manual klasik yang diterjemahkan tetap tersedia di Pengaturan .NET 6 Warisan. Gerbang integrasi Klasik yang baru menjelaskan sinyal identifikasi yang sama dan menautkan kembali ke panduan migrasi ini.

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