Rozwiązywanie problemów

Diagnozowanie typowych błędów

Każda poniższa wiadomość to dosłowny tekst generowany przez Doconut, uporządkowany według objawów. Znajdź swój błąd i zastosuj rozwiązanie.

Podgląd nic nie wyświetla

Pusty obszar podglądu, konsola przeglądarki pełna 404 dla /doconut-res/...
UseDoconutResources() jest brakujące lub umieszczone po UseDoconut(). Musi być pierwsze w potoku.

HTTP 500 z:

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

Bezpieczeństwo tokenów Doconut (włączone domyślnie) wymaga stanu sesji ASP.NET. Dodaj builder.Services.AddSession() oraz app.UseSession() przed gałęzią pośredniczącą Doconut. Stan sesji wymaga również pamięci podręcznej: w aplikacji minimal‑API dodaj builder.Services.AddDistributedMemoryCache(), w przeciwnym razie aplikacja zatrzyma się przy uruchamianiu z komunikatem Unable to resolve service for type 'IDistributedCache' (aplikacje MVC i Razor Pages rejestrują ją domyślnie).

Obrazek błędu w obszarze strony z napisem:

text
You Are Not Authorized To View This Page.

Token został otwarty w innej sesji przeglądarki. Typowe przyczyny: ciasteczko sesji nie dociera do żądań strony (konfiguracja cross‑origin, polityka SameSite, klient API bez pojemnika na ciasteczka) lub aplikacja została zrestartowana (nowe klucze sesji). To warstwa zabezpieczeń działająca zgodnie z zamierzeniem — zobacz Core Concepts → Sessions & Security.

Obrazek błędu z napisem:

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

Token wygasł (przesuwne okno, domyślnie 60 minut — DocOptions.TimeOut) lub sesja została zamknięta. Otwórz dokument ponownie, aby uzyskać nowy token.

Nie udaje się otworzyć dokumentu

LicenseException z komunikatem odrzucenia — plik licencji został znaleziony, ale odrzucony (nieprawidłowy podpis, uszkodzony, na czarnej liście lub wersja/okno aktualizacji nie obejmuje bieżącej kompilacji). Ten stan blokuje otwieranie (fail‑fast) zamiast degradacji do znaku wodnego; odczytaj License.RejectionMessage, aby poznać przyczynę.

LicenseException:

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

Rozszerzenie obsługiwane jest wyłącznie przez wtyczkę (tutaj: DICOM) i nie ma już przyznanej możliwości. Zarejestruj wtyczkę i sprawdź lic.IsCapabilityGranted(LicenseCapability.Dicom). Brak lub niewystarczające nie‑tymczasowe uprawnienie zwykle powoduje błąd wcześniej, podczas AddDoconut().

FormatNotSupportedException:

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

Żaden podgląd — wbudowany, wtyczka ani własny — nie obsługuje tego rozszerzenia. Sprawdź listę obsługiwanych formatów; dla własnych formatów można dodać obsługę przez DoconutOptions.RegisterViewer.

InvalidDataException — zawartość pliku jest uszkodzona lub nie pasuje do jego rozszerzenia (np. plik został przemianowany). Waliduj przesyłane pliki przed otwarciem.

InvalidOperationException:

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

Rozwiązałeś DocumentConverter bez zarejestrowania wtyczki konwertera.

Nie udaje się uruchomić aplikacji

InvalidOperationException wspominający wtyczkę zarejestrowaną przez AddPlugin — bieżąca nie‑tymczasowa licencja nie przyznaje tej możliwości wtyczki. Usuń rejestrację lub zainstaluj licencję, która ją przyznaje. Brak licencji oraz starszy plik TRIAL nie przyznają żadnych możliwości wtyczek.

ArgumentException z 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.

Walidacja opcji w trybie fail‑fast — popraw nieprawidłową ścieżkę.

Błędy kompilacji / zależności

Błąd kompilatora CS1705, lub w czasie działania przy otwieraniu dokumentu:

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

Twój projekt wymusza wersję System.Text.Json lub System.Text.Encodings.Web niższą niż 8.0.x zadeklarowaną przez Doconut.NET6. Usuń downgrade i pozwól NuGet przywrócić graf pakietów (System.Text.Json 8.0.6 i System.Text.Encodings.Web 8.0.0 w pakiecie audytowanym 26.7.0).

TypeInitializationException przy pierwszym pliku prezentacji:

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

Silnik prezentacji wymaga System.Drawing.Common 6.0.0 (zadeklarowanego w pakiecie). Nie usuwaj ani nie nadpisuj tej zależności — każde otwarcie PPT/PPTX/PPS/POT/ODP bez niej kończy się niepowodzeniem.

Wyjście wygląda niepoprawnie

Strony mają znak wodny — aplikacja działa w trybie ewaluacyjnym: brak pliku licencji, wygasłe okno tymczasowe lub subskrypcji, albo nieprawidłowa domena. Sprawdź IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — odniesienie do IDoconutLicenseService na stronie Licensing wskazuje gotowy punkt końcowy.

Starsze dokumenty wyświetlają zniekształcony tekst — kodowanie stron kodowych nie jest domyślnie ładowane w .NET 6. Dodaj raz przy starcie:

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

Nieprawidłowe lub zastąpione czcionki w Linux/Docker — kontener nie zawiera czcionek dokumentu. Skieruj FontFolders (w WordConfig/PptConfig) na zamontowany katalog czcionek.

Prezentacje otwierają się, ale nie renderują w Linux/macOS — aktualny renderer PPT/PPTX/PPS/POT/ODP wymaga natywnego libgdiplus oraz System.Drawing.EnableUnixSupport=true. Pakiet dostarcza System.Drawing.Common 6.0.0, ponieważ jest to ostatnia wersja honorująca ten przełącznik.

Funkcja działała w wersji ewaluacyjnej, milczy w produkcji

Klasyczny szok po uruchomieniu: aktywna licencja tymczasowa przyznaje wszystkie możliwości; zakupiona licencja przyznaje tylko to, co zostało kupione. Pakiety wyszukiwania i adnotacji mogą zniknąć, gdy brakuje odpowiednich możliwości. Zarejestrowane wtyczki Converter lub DICOM z niewystarczającą nie‑tymczasową licencją zawodzą podczas AddDoconut(). Porównaj IsCapabilityGranted(...) z każdą funkcją, którą włączasz przed wdrożeniem.

Wyszukiwanie nie znajduje nic (lub zbyt mało)

  • Dla bezpośredniego PDF, AllowSearch nie został włączony w momencie otwarcia. Word, Excel i PowerPoint udostępniają tę samą opcję poprzez ich zagnieżdżony PdfConfig.
  • Zawartość jest skanowana/tylko obraz, więc standardowe wyszukiwanie nie ma warstwy tekstowej do dopasowania. Użyj źródła zawierającego tekst lub projekcji PDF zachowującej tekst.
  • HTML i MS Project (MPP) nie są przeszukiwalne domyślnie — ustaw DefaultRender = false, aby renderowały się jako projekcja PDF z natywną warstwą tekstową. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB i MHT są przeszukiwalne w ich domyślnych ustawieniach katalogu.
  • objViewer.CanSearch() zwraca false po inicjalizacji — rozpoznany format nie ma standardowej ścieżki wyszukiwania. Ten werdykt jest oddzielny od licencji Search; zweryfikuj oba.

Wciąż utknąłeś?

Izoluj problem w minimalnej aplikacji Quick Start; jeśli tam się powtarza, skontaktuj się z pomocą techniczną, przekazując dokument, swój Program.cs oraz wyjście diagnostyki licencji.

Czy ta strona była pomocna?