Sorun Giderme

Yaygın hataları teşhis edin

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

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

Boş görüntüleyici alanı, tarayıcı konsolu /doconut-res/... için 404 hatalarıyla dolu UseDoconutResources() eksik veya UseDoconut()'dan sonra yer alıyor. Boru hattında ilk olarak gelmelidir.

HTTP 500 ile:

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 ayrıca bir önbellek gerektirir: minimal-API uygulamasında builder.Services.AddDistributedMemoryCache() ekleyin, aksi takdirde uygulama Unable to resolve service for type 'IDistributedCache' hatasıyla başlatmada durur (MVC ve Razor Pages uygulamaları zaten bir tane kaydeder).

Sayfa alanında şu hatayı gösteren bir görüntü:

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şmıyor (çapraz köken ayarı, SameSite politikası, çerez kutusu olmayan bir API istemcisi) veya uygulama yeniden başlatıldı (yeni oturum anahtarları). Bu, tasarlandığı gibi çalışan güvenlik katmanıdır — Core Concepts → Sessions & Security bölümüne bakın.

Şu hatayı gösteren bir görüntü:

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

Token süresi doldu (kaydırmalı pencere, varsayılan 60 dakika — DocOptions.TimeOut) veya oturum kapatıldı. Yeni bir token için belgeyi yeniden açın.

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

LicenseException reddetme mesajı ile — lisans dosyası bulundu ancak reddedildi (geçersiz imza, bozulmuş, kara listeye alınmış veya lisansın sürüm/güncelleme penceresinin dışındaki bir yapı). Bu durum, belgeyi açmayı (hızlı başarısız) engeller; su işaretiyle bozulmaz; nedeni öğrenmek için License.RejectionMessage okuyun.

LicenseException:

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

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

FormatNotSupportedException:

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

Hiçbir görüntüleyici — yerleşik, eklenti veya özel — bu uzantıyı desteklemiyor. Desteklenen format listesini kontrol edin; kendi formatlarınız için DoconutOptions.RegisterViewer bir tane ekleyebilir.

InvalidDataException — dosya içeriği bozuk veya uzantısıyla eşleşmiyor (ör. yeniden adlandırılmış bir 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'ı kaydetmeden Converter eklentisini eklediniz.

Başlangıç başarısız

InvalidOperationException AddPlugin ile kaydedilen bir eklentiden bahsediyor — mevcut geçici olmayan lisans o eklenti yeteneğini vermiyor. Kaydı kaldırın veya yetki veren bir lisans yükleyin. Eksik bir lisans ve eski bir TRIAL dosyası hiçbir eklenti yetkisi 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ı başarısız seçenek doğrulaması — hatalı yolu düzeltin.

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

Derleyici hatası CS1705, veya bir belge açarken çalışma zamanında:

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

Projeniz Doconut.NET6 tarafından ilan edilen 8.0.x bağımlılıklarının altında System.Text.Json veya System.Text.Encodings.Web sabitlemiş. Sürüm düşürmeyi kaldırın ve NuGet'in paket grafiğini (denetlenen 26.7.0 paketindeki System.Text.Json 8.0.6 ve System.Text.Encodings.Web 8.0.0) geri yüklemesine izin verin.

TypeInitializationException ilk sunum dosyasında:

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

Sunum motoru System.Drawing.Common 6.0.0'ı (paket tarafından ilan edilen) kesinlikle gerektirir. Bu bağımlılığı kaldırmayın veya geçersiz kılmayın — her PPT/PPTX/PPS/POT/ODP açma bu olmadan başarısız olur.

Çıktı yanlış görünüyor

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

Eski belgeler bozuk metin gösteriyor — kod sayfası kodlamaları .NET 6'da varsayılan olarak yüklenmez. Başlangıçta bir kez ekleyin:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Linux/Docker'da yanlış veya yerine konmuş yazı tipleri — konteyner belge yazı tiplerine sahip değil. FontFolders (on WordConfig/PptConfig) bir bağlanmış yazı tipi dizinine işaret etsin.

Sunumlar açılıyor ancak Linux/macOS'ta render edilemiyor — mevcut PPT/PPTX/PPS/POT/ODP renderlayıcı 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 modunda çalıştı, üretimde sessiz

Klasik canlıya geçiş sürprizi: aktif Geçici lisans her yeteneği verir; satın aldığınız lisans yalnızca satın aldıklarınızı verir. Arama ve açıklama paketleri, yetenekleri eksik olduğunda kaybolabilir. Yetersiz geçici olmayan bir lisansla kayıtlı Converter veya DICOM eklentileri AddDoconut() sırasında başarısız olur. Dağıtıma almadan önce etkinleştirdiğiniz her özelliği IsCapabilityGranted(...) ile karşılaştırın.

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

  • Doğrudan PDF için, AllowSearch açma sırasında 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ına sahip değildir. 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 ayarlayın, böylece yerel bir metin katmanına sahip PDF projeksiyonu üzerinden render ederler. Word, Excel, PowerPoint, TXT, Visio, e‑posta, EPUB ve MHT katalog varsayılanlarında aranabilir.
  • objViewer.CanSearch() başlatmadan sonra false döner — çözülen format standart bir arama yolu içermiyor. Bu karar, Arama lisansından ayrı bir durumdur; ikisini de doğrulayın.

Hâlâ takıldı mı?

Sorunu minimal Quick Start uygulamasıyla izole edin; eğer orada da tekrarlanıyorsa, belge, Program.cs dosyanız ve lisans tanı teşhis çıktısı ile destekle iletişime geçin.

Bu sayfa yardımcı oldu mu?