Sorun Giderme

Yaygın hataları teşhis edin

Aşağıdaki her mesaj, Doconut'ın ü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

Görüntüleyici alanı boş, tarayıcı konsolu /doconut-res/... için 404'lerle dolu
UseDoconutResources() eksik veya UseDoconut()'dan sonra yer alıyor. İlk aşamada iş akışı içinde bulunmalıdır.

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() önce 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şlatma sırasında durur (MVC ve Razor Pages uygulamaları zaten bir tanesini kaydeder).

Sayfa alanında şu metni içeren bir hata resmi:

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 kaynak yapılandırması, SameSite politikası, çerez tutucu 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 metni içeren bir hata resmi:

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 penceresi dışındaki bir yapı). Bu durum, belgeyi açmayı (hızlı başarısız) engeller; bir filigrana düşürmek yerine; nedeni öğrenmek için License.RejectionMessage'ı okuyun.

LicenseException:

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

Bu uzantı yalnızca bir eklenti (burada: DICOM) tarafından işlenir ve yetenek artık verilmemiştir. Eklentiyi kaydedin ve lic.IsCapabilityGranted(LicenseCapability.Dicom) ile doğrulayın. Eksik veya 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.

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ış 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>().

Converter eklentisini kaydetmeden DocumentConverter'ı çözdünüz.

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

InvalidOperationException AddPlugin ile kaydedilen bir eklentiden bahsediyor — mevcut geçici olmayan lisans bu eklenti yeteneğini vermiyor. Kaydı kaldırın veya yetki veren bir lisans yükleyin. Eksik bir lisans ve eski TRIAL dosyası hiçbir eklenti yetkisi vermez.

ArgumentException from AddDoconut():

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ızlık seçenek doğrulaması — hatalı yolu düzeltin.

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

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

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

Projeniz System.Text.Json / System.Text.Encodings.Web paketlerini 10.0.x'in altında sabitledi. Sürüm düşürmeyi kaldırın ve NuGet'in Doconut.NET8 tarafından bildirilen sürümleri geri yüklemesine izin verin.

İ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ü kesinlikle gerektirir (paket tarafından bildirildi). 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ı 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, veya 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 görüntüleniyor — kod sayfası kodlamaları .NET 8'de varsayılan olarak yüklenmez. Başlangıçta bir kez ekleyin:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Linux/Docker üzerinde yanlış veya yerine konulan yazı tipleri — konteyner belgeye ait yazı tiplerine sahip değil. FontFolders'ı (WordConfig/PptConfig üzerinde) 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ı onaylayan son sürüm olduğu için System.Drawing.Common 6.0.0 sağlar.

Özellik değerlendirme ortamında çalıştı, üretimde sessiz

Klasik canlı yayına geçiş sürprizi: aktif Temporary lisansı her yeteneği verir; satın aldığınız lisans sadece satın aldıklarınızı verir. Arama ve ek 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 önceden etkinleştirdiğiniz her özelliği IsCapabilityGranted(...) ile karşılaştırın.

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

  • Doğrudan bir 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ğu için 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 ayarlarında aranabilir değildir — DefaultRender = false ayarlayarak PDF projeksiyonu üzerinden yerel bir metin katmanı ile render edilmelerini sağlayın. Word, Excel, PowerPoint, TXT, Visio, e‑posta, EPUB ve MHT katalog varsayılanlarında aranabilir.
  • objViewer.CanSearch() başlatma sonrası 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ı?

Problemi minimal Quick Start uygulamasıyla izole edin; eğer orada da tekrarlanıyorsa, belgeyi, Program.cs dosyanızı ve lisans tanı teşhis çıktısını destek ekibiyle paylaşın.

Bu sayfa yardımcı oldu mu?