Sorun Giderme

Yaygın hataları teşhis edin

Aşağıdaki her mesaj, Doconut'un ürettiği tam metindir ve semptomlara göre düzenlenmiştir. Hatanızı bulun, düzeltmeyi uygulayın.

Görüntüleyici hiçbir şey göstermiyor

Boş görüntüleyici alanı, tarayıcı konsolu /doconut-res/... için 404 hatalarıyla dolu
UseDoconutResources() eksik ya da UseDoconut() sonrasında yer alıyor. İlk olarak pipeline’da bulunmalıdır.

HTTP 500 hatası şu mesajla:

text
Session middleware not configured. Call UseSession() before UseDoconut().

Doconut'un token güvenliği (varsayılan olarak açıktır) ASP.NET oturum durumuna ihtiyaç duyar. builder.Services.AddSession() ve app.UseSession() Doconut ara katmanı dalından önce ekleyin. Oturum durumu bir önbellek de gerektirir: minimal‑API uygulamasında builder.Services.AddDistributedMemoryCache() ekleyin, aksi takdirde uygulama Unable to resolve service for type 'IDistributedCache' hatasıyla başlatma sırasında durur (MVC ve Razor Pages uygulamaları zaten bir tane kaydeder).

Sayfa alanında şu hatayı gösteren bir resim:

text
You Are Not Authorized To View This Page.

Token farklı bir tarayıcı oturumu tarafından açıldı. Yaygın nedenler: oturum çerezi sayfa isteklerine ulaşamıyor (çapraz‑origin yapılandırması, SameSite politikası, çerez kavanozu olmayan bir API istemcisi) veya uygulama yeniden başlatıldı (yeni oturum anahtarları). Bu, tasarlandığı gibi çalışan güvenlik katmanıdır — Temel Kavramlar → Oturumlar ve Güvenlik bölümüne bakın.

Şu hatayı gösteren bir resim:

text
Document session not found. Please re-open document.

Token süresi dolmuş (kaydırmalı pencere, varsayılan 60 dakika — DocOptions.TimeOut) ya da oturum kapatılmış. Yeni bir token için belgeyi yeniden açın.

Sunucu iyi çalışıyor ama sayfa hatalı davranıyor — hiçbir hata yok

Bunlar, bir uygulamayı ileri taşıdıktan sonra ilk şüphelenmeniz gereken hata modlarıdır. Üçü de sunucunun sorunsuz çalışmasını, belgenin doğru şekilde render edilmesini ve tarayıcı konsolunda hiçbir şey raporlanmamasını sağlar.

Hiç durmayan bir yükleme çarkı. Görüntüleyici geri çağrılarınız, konteyner kimliğine göre adlandırılmış global fonksiyonlar olarak tanımlanmıştır — ctlDoc_OnViewerReady() ve benzerleri. Önceki görüntüleyici bu isimleri arıyordu; bu sefer aramıyor. Çarkı gizleyecek işleyici hiç çalışmadı. Fonksiyonları seçenek olarak geçirin:

javascript
objctlDoc = $('#div_ctlDoc').docViewer({
    onViewerBusy:     ctlDoc_OnViewerBusy,
    onViewerReady:    ctlDoc_OnViewerReady,
    onCopy:           ctlDoc_Copy,
    onAutoLoadStatus: ctlDoc_AutoLoadStatus
});

Çarkın arkasındaki belge sorunsuzdur. Tam seçenek listesi GörüntüleyiciYapılandırması içinde bulunur.

Görünüm simgeleri veya çerçevesi eksik, sayfalar başka türlü doğru. ResPath boş ya da uygulama köküne işaret ediyor — önceki kütüphanede doğru, burada yanlış. UseDoconutResources() tarafından monte edilen önek olmalıdır:

javascript
ResPath: 'doconut-res/images'   // veya '<your ResourcesPath>/images'

Paylaşılan depolamadan hizmet verirken sonraki sayfalarda bozuk kareler. Henüz yazılmakta olan sayfalar 202 Accepted yanıtı verir. retryOn409: true ayarı olmayan bir istemci bunu başarısız bir resim olarak değerlendirir. Dağıtık Dağıtımlar bölümüne bakın.

Bir belge açma başarısız oluyor

LicenseException ve bir reddetme mesajı — lisans dosyası bulundu ancak reddedildi (geçersiz imza, değiştirilmiş, kara listeye alınmış veya lisansın sürüm/güncelleme penceresi dışındaki bir derleme). Bu durum, belgeyi su işaretiyle degrade etmek yerine (hızlı‑başarısız) açmayı engeller; nedeni öğrenmek için License.RejectionMessage değerine bakın.

LicenseException:

text
This document type requires the 'Dicom' plugin license.

Bu uzantı yalnızca bir eklenti (burada: DICOM) tarafından işlenir ve yetki artık verilmemiştir. Eklentiyi kaydedin ve lic.IsCapabilityGranted(LicenseCapability.Dicom) ile doğrulayın. Eksik ya da yetersiz geçici olmayan bir yetki, genellikle AddDoconut() sırasında daha önce başarısız olur.

FormatNotSupportedException:

text
Document format '<extension>' is not supported.

Yerleşik, eklenti ya da özel bir görüntüleyici bu uzantıyı tanımıyor. Desteklenen‑format listesine bakın; kendi formatlarınız için DoconutOptions.RegisterViewer bir tane ekleyebilir.

InvalidDataException — dosya içeriği bozuk ya da uzantısıyla eşleşmiyor (ör. yeniden adlandırılmış dosya). Açmadan önce yüklemeleri doğrulayın.

InvalidOperationException:

text
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().

DocumentConverterı çözdünüz ancak Dönüştürücü eklentisini kaydetmediniz.

Başlangıçta başarısızlık

InvalidOperationException bir eklentinin AddPlugin ile kaydedildiğini belirtiyor — mevcut geçici olmayan lisans bu eklenti yeteneğini sağlamaz. Kaydı kaldırın veya yetki veren bir lisans yükleyin. Eksik bir lisans ve eski bir TRIAL dosyası hiçbir eklenti yeteneği vermez.

ArgumentException AddDoconut()'dan:

text
DoconutOptions.MiddlewarePath must be a non-empty path starting with '/'.
DoconutOptions.ResourcesPath must be a non-empty path starting with '/'.
DoconutOptions.MiddlewarePath and ResourcesPath must be different paths.

Hızlı hata ayıklama seçenek doğrulaması — hatalı yolu düzeltin.

Derleme / bağımlılık hataları

Paket hiç kurulamaz — Doconut.NETStandard 26.8.0 netstandard2.1 hedefliyor, bu yüzden NuGet bir .NET Framework projesini reddediyor. Bu çözülemeyen bir geri yükleme hatası değildir: .NET Framework netstandard2.1'i tüketemez. Bunun yerine Doconut.NETFramework paketini kullanın.

Derleyici hatası CS1705, ya da bir belge açılırken çalışma zamanı hatası:

text
Could not load file or assembly 'System.Text.Json, Version=9.0.0.0'

Projeniz System.Text.Json veya System.Text.Encodings.Web paketini Doconut.NETStandard tarafından bildirilen 9.0.x bağımlılıklarının altında sabitlemiş. Düşürmeyi kaldırın ve NuGet'in paket grafiğini (System.Text.Json 9.0.0 ve System.Text.Encodings.Web 9.0.0, denetlenen 26.8.0 paketinde) geri yüklemesine izin verin.

Paketi yükselttikten hemen sonra bir duvar gibi derleme hataları — bu beklenen bir durum. 26.8.0, 26.7.0'dan farklı bir API yüzeyine sahiptir, uyumlu bir güncelleme değildir. Hataların çoğu, kök Doconut ad alanına taşınan using satırlarıdır; bunları tek tek yamalamak yerine .NET Standard 2.1'e Geçiş rehberini izleyin.

İlk sunum dosyasında TypeInitializationException:

text
Could not load ... System.Drawing.Common, Version=6.0.0.0

Sunum motoru System.Drawing.Common 6.0.0 sürümünü zorunlu olarak ister (paket tarafından bildirilen). Bu bağımlılığı kaldırmayın veya geçersiz kılmayın — her PPT/PPTX/PPS/POT/ODP açma işlemi onsuz başarısız olur.

Çıktı hatalı görünüyor

Sayfalarda filigran var — uygulama değerlendirme modunda: lisans dosyası bulunamadı, süresi dolmuş geçici veya abonelik penceresi, ya da geçersiz bir alan adı. IDoconutLicenseService'i inceleyin (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — Lisanslama sayfasının IDoconutLicenseService referansı hazır bir uç nokta gösterir.

Eski belgeler bozuk metin olarak render ediyor — kod sayfası kodlamaları varsayılan olarak yüklenmez. Başlangıçta bir kez ekleyin:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Linux/Docker'da yanlış veya yer değiştirmiş yazı tipleri — konteyner belgeye ait yazı tiplerine sahip değil. FontFolders'ı (WordConfig/PptConfig içinde) bağlanmış bir yazı tipi dizinine yönlendirin.

Sunumlar açılıyor ancak Linux/macOS'ta render edilemiyor — mevcut PPT/PPTX/PPS/POT/ODP renderlayıcısı yerel libgdiplus ve System.Drawing.EnableUnixSupport=true gerektirir. Paket, bu anahtarı destekleyen son sürüm olduğu için System.Drawing.Common 6.0.0'ı sağlar.

Özellik değerlendirme sırasında çalışıyordu, üretimde sessiz

Klasik canlıya geçiş sürprizi: etkin Geçici lisans tüm yetenekleri verir; satın aldığınız lisans sadece satın aldığınız şeyleri kapsar. Arama ve açıklama paketleri, yetenekleri eksik olduğunda kaybolabilir. Yetersiz geçici olmayan bir lisansla AddDoconut() sırasında kaydedilen DICOM eklentileri başarısız olur. Dağıtıma başlamadan önce etkinleştirdiğiniz her özelliği IsCapabilityGranted(...) ile karşılaştırın.

Arama hiçbir şey bulamıyor (ya da çok az)

  • Doğrudan bir PDF için, açılışta AllowSearch etkinleştirilmemişti. Word, Excel ve PowerPoint aynı anahtarı iç içe PdfConfig üzerinden sunar.
  • İçerik taranmış/görüntü‑only olduğundan, normal Arama eşleşecek bir metin katmanı bulamaz. Metin içeren bir kaynak ya da metni koruyan bir PDF projeksiyonu kullanın.
  • HTML ve MS Project (MPP) varsayılan olarak aranabilir değildir — DefaultRender = false olarak ayarlayın, böylece yerel bir metin katmanı olan PDF projeksiyonu ile renderlanırlar. Word, Excel, PowerPoint, TXT, Visio, e‑posta, EPUB ve MHT varsayılan katalog ayarlarıyla aranabilir.
  • objViewer.CanSearch() başlatma sonrası false döner — çözülen format standart bir arama yoluna sahip değildir. Bu karar, Arama lisansından ayrı bir değerlendirmedir; ikisini de doğrulayın.

Hâlâ takıldınız mı?

Sorunu minimal Quick Start uygulamasında izole edin; eğer orada da tekrarlanıyorsa, belgeyle, Program.cs dosyanızla ve lisans tanı teşhis çıktısıyla destek birimine başvurun.

Bu sayfa yardımcı oldu mu?