Klasik .NET 6 entegrasyonundan geçiş

Doconut iki ayrı .NET 6 entegrasyonuna sahiptir. Aynı Doconut.NET6 paket adını kullanabilirler, bu yüzden paketleri, başlangıç dosyalarını, lisansları veya tarayıcı kaynaklarını değiştirmeden önce uygulamadaki API'lerden jenerasyonu belirleyin.

Hangi .NET 6 entegrasyonunu kullanıyorsunuz?

Her iki sütun aynı uygulamada bulunuyorsa, geçişi eksik olarak değerlendirin. Bir jenerasyondan diğerine kaynaklar veya ara katman üzerinden bir belge token'ı göndermeyin.

NuGet paket adının size ne söyleyemeyebileceği

Her iki jenerasyon da Doconut.NET6 paket kimliği altında dağıtılmıştır. Bir paket referansı, kilit dosyası veya önbelleğe alınmış .nupkg tek başına barındırma API'sını tanımlamaz. Tam paket sürümünü kaydedin ve Program.cs, viewer oluşturma, belge açma ve tarayıcı betiklerini birlikte inceleyin.

Bu kılavuz için denetlenen mevcut sürüm Doconut.NET6 26.7.0'dır. İsteğe bağlı genel paketleri Doconut.NET6.Converter ve Doconut.NET6.Dicom olup, çekirdek paketle aynı sürümde sabitlenmiştir.

Geçişten önce

1. Mevcut uygulamanın bir dalını ve dağıtılabilir bir yedeğini oluşturun.
2. Tam çekirdek ve eklenti paket sürümlerini kaydedin.
3. Her DocImage.axd eşlemesini, new Viewer(...) çağrısını, lisans‑yükleme çağrısını, kopyalanmış Doconut betiğini, özel araç çubuğu eylemini ve belge‑açma uç noktasını envantere alın.
4. Mevcut .lic dosyalarını ve dağıtım gizli anahtarlarını kaynak kontrolünün dışına çıkarın.
5. PDF, Office, resim, CAD, e‑posta, DICOM, aranabilir, şifre‑korumalı ve açıklamalı belgelerden temsilci bir set yakalayın.
6. Mevcut oturum zaman aşımını, güvenlik davranışını, yazı tiplerini ve platform ayarlarını kaydedin.

Üretim ortamını değiştirmeden önce bir ortamda geçiş yapın. Mevcut entegrasyon hizmet ömrünü, istek yönlendirmesini, oturum sahipliğini ve istemci kaynak teslimini değiştirir.

Paket ve lisans uyumluluğu

Çekirdek paketi kasıtlı olarak değiştirin; aynı paket kimliğine dayanarak yeni API'yı seçmeye çalışmayın. Varsayılan komut en son kararlı sürümü kurar:

dotnet add package Doconut.NET6

Bu kılavuz tarafından denetlenen sürüme yeniden üretilebilir bir geçiş yapmak için sürümü ayrı bir seçenek olarak iletin:

dotnet add package Doconut.NET6 --version 26.7.0

Her Doconut eklentisini çekirdek paketle aynı sürümde tutun. Mevcut entegrasyon lisansları AddDoconut() sırasında bir kez yükler ve şu önceliği kullanır:

LicenseStream > LicenseContent > LicensePath > otomatik keşif

Otomatik keşif Doconut.Viewer.lic ve eşlik eden Doconut.Viewer.<Capability>.lic dosyalarını arar. Viewer.DoconutLicense(...) veya Viewer.SetLicensePlugin(...) çağrısı klasik bir başlangıç mekanizması değildir. Lisansı DoconutOptions içine taşıyın, otomatik keşif kullanırken eşlik eden dosyaları birlikte tutun, bir lisans değişikliğinden sonra yeniden başlatın ve yetenekleri IDoconutLicenseService aracılığıyla doğrulayın.

Eski bir eklenti lisansının varlığının mevcut bir eklenti derlemesi için hak sağladığını varsaymayın. Viewer, Search, Annotation, Converter ve DICOM’u onaylı sürüm artefaktlarıyla ayrı ayrı test edin.

Başlangıç ve bağımlılık enjeksiyonu

Klasik uygulamalar Viewer'ı ASP.NET önbelleği ve istek‑erişimi bağımlılıklarıyla oluşturur:

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

Mevcut entegrasyon Doconut'u bir kez kaydeder ve Viewer'ı bağımlılık enjeksiyonundan alır:

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

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

Viewer geçici (transient) bir hizmettir. Belge oturum yöneticisi ve önbelleği daha uzun ömürlü belge durumunu, belirli enjekte edilmiş Viewer örneğinden ayrı tutar.

Ara katman ve kaynak yönlendirme

DocImage.axd'yi algılayan klasik MapWhen dalını kaldırın:

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

Mevcut işlem hattında:

1. Oturum güvenliği etkinken UseSession()'ı Doconut'tan önce çağırın;
2. UseDoconutResources()'ı UseDoconut()'dan önce çağırın;
3. ResourcesPath, oluşturulan kaynak URL'leri ve istemci ResPath'i hizalı tutun;
4. UseDoconut()'ı bir dala eşlerken, o dalı ve istemci BasePath'i hizalı tutun.

MiddlewarePath doğrulanmış bir yapılandırmadır; tek başına bir ASP.NET Core dalı oluşturmaz. Yukarıdaki derlenebilir örnekten basit işlem hattını ya da istemci tarafından tutarlı şekilde kullanılan app.Map("/doconut", branch => branch.UseDoconut()) düzenlemesini kullanın.

Viewer oluşturma ve ömür yönetimi

Viewer nesnelerinin uygulama‑sahibi önbelleklerini kaldırın. Viewer'ı bir uç noktaya, Razor sayfasına, denetleyiciye veya kapsamlı bir uygulama hizmetine enjekte edin:

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

Döndürülen token bir sunucu‑tarafı belge oturumunu tanımlar. Bunu bir taşıyıcı kimlik bilgisi gibi davranın: kaydetmeyin, kalıcı hale getirmeyin ve analizlerde kullanmayın.

Belgeleri açma ve kapama

Senkron OpenDocument(...) yerine OpenDocumentAsync(...) kullanın:

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

Mevcut aşırı yüklemeler bir dosya yolu veya akış, isteğe bağlı format yapılandırması, isteğe bağlı DocOptions ve bir iptal token'ı kabul eder. Tarayıcı belgeye artık ihtiyaç duymadığında sunucu oturumunu açıkça kapatın:

viewer.CloseDocument(token);

Geçiş sonrası klasik bir token'ı yeniden kullanmayın. Her belgeyi mevcut API üzerinden tekrar açın.

Yapılandırma sınıfları

Mevcut API sorumlulukları ayırır:

DocOptions.ImageResolution'ı render kontrolü olarak taşımayın. Artık kullanılmamaktadır; format‑özel yapılandırmada BaseConfig.ImageResolution ayarlayın. Tüm varsayılanları gözden geçirin; klasik bir yapılandırmanın aynı davranışı gösterdiğini varsaymayın.

Viewer araç çubuğu, Arama ve Açıklama

Eski betikleri tek tek taşımayın. Mevcut referans uygulamalar bir tam sayfa paketi oluşturur:

1. ReferenceCss ile Viewer CSS ve lisanslı Arama/Açıklama CSS'sini yayınlayın;
2. Uygulama‑sahibi Viewer araç çubuğunu render edin;
3. searchBarMount, annBarMount ve gerekli Viewer montajını render edin;
4. ReferenceScripts ile Viewer ve lisanslı modül betiklerini yayınlayın;
5. Uygulamanın kendi viewerToolbar.js dosyasını yükleyin;
6. Bir objViewer başlatın;
7. Lisanslı Arama ve Açıklama Şeritlerini başlatın;
8. Her Şeritte attach(objViewer) çağırın;
9. Belgeyi açın ve objViewer.View(token) çağırın.

Arama ve Açıklama aynı Viewer'a eklenen modüllerdir, bağımsız araç çubukları değildir. Ana araç çubuğu host uygulamaya aittir; Arama ve Açıklama Şeritleri gömülü, yetenek‑kontrollü kaynaklardır.

documentLinks.js ve docViewer.UI.js gibi manuel kopyalanmış klasik dosyaları yalnızca ReferenceCss ve ReferenceScripts tarafından yayınlanan kaynaklar çalıştıktan sonra kaldırın.

Eklenti kaydı

Klasik statik eklenti‑lisans yöntemleri mevcut eklentileri kaydetmez. Her yayınlanan paketi açıkça kurun ve kaydedin:

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

AddDoconut() başlangıçta kayıtlı eklenti yeteneklerini doğrular. Converter ve DICOM .NET 6 için yayınlanmış eklentilerdir. Normal Arama ve Açıklama yerleşik lisanslı özelliklerdir; AddPlugin<TPlugin>() paketleri değildir.

Oturum ve belge güvenliği

Mevcut entegrasyon belgeleri opak token'lar ve önbellekli oturumlarla bağlar. Varsayılan UnsafeMode = false ile UseDoconut() belge‑erişim güvenliği ekler ve host'un ASP.NET oturumunu yapılandırması gerekir:

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

DocOptions.IsSecured = true tutun; aksi bir tasarım gözden geçirilmedikçe değiştirmeyin. Geçiş kısayolu olarak UnsafeMode = true kullanmayın. Token olmadan, bozuk token, süresi dolmuş token ve farklı bir tarayıcı oturumundan gelen token ile istekleri test edin.

Dağıtık referans uygulaması erişim biletleri ve taşıma detayları ekler. Bu API'lar normal tek‑düğüm geçişi için gerekli değildir.

Geçişi test etme

En azından şunları doğrulayın:

• Üretim lisansı ve tüm kayıtlı eklentilerle uygulama başlangıcı;
• Seçilen yollar altında Viewer CSS/skriptleri ve tüm sayfa‑resim istekleri;
• Belge açma, gezinme, yakınlaştırma, küçük resimler, yazdırma ve açıkça kapama;
• Metin içeren bir belgede Arama ve yalnızca resim dosyasında arama yapılamaz durumu;
• Açıklama yükleme, kaydetme, dışa aktarma ve yetenek kontrolü;
• Converter hedef keşfi, çıktı, indirme ve filigran durumu;
• DICOM sayfaları, çerçeveler ve animasyon; .NET 6 teknik meta verileri mevcut değil;
• Şifre‑korumalı belgeler, özel yazı tipleri, Latin dışı metin ve yapılandırılmış zaman aşımı;
• Çapraz‑oturum token reddi ve süresi dolmuş oturum davranışı;
• Mobil, karanlık mod ve üretim ters‑proxy yolu.

Geri dönüş planı

Klasik dağıtım artefaktını, eşleşen paketleri, lisans dosyalarını ve kopyalanmış tarayıcı kaynaklarını birlikte tutun. Güvenli bir geri dönüş, tüm uygulama jenerasyonunu değiştirir; klasik bir sunucuyu mevcut betiklerle veya mevcut bir sunucuyu klasik DocImage.axd çağrılarıyla karıştırmaz.

Kesinti öncesinde belgeleyin:

• Geri dönüş için kullanılan dağıtım yuvası veya artefakt;
• Veritabanı/önbellek etkisi, varsa;
• Aktif belge oturumlarının nasıl geçersiz kılınacağı;
• Geri dönüş kararını vermek için kullanılan sağlık kontrolü ve test belgesi;
• Önceki paket setini ve yapılandırmayı kim geri yükleyebilir.

Eski belgeler

Klasik el kitabının çevrilmiş sürümü şu adreste mevcuttur: Legacy .NET 6 kurulumu. Yeni Klasik entegrasyon geçidi aynı tanımlama sinyallerini açıklar ve bu geçiş kılavuzuna geri bağlanır.

Yer işaretlerinde ve destek taleplerinde tarihsel URL'yi tutun; klasik kurulumlar hâlâ var olduğunda farklı bir jenerasyonu belgelediği için mevcut API'ye yönlendirilmez.