Rozwiązywanie problemów

Diagnozuj typowe błędy

Poniżej znajdują się dosłowne komunikaty generowane przez Doconut, uporządkowane według objawów. Znajdź swój błąd i zastosuj rozwiązanie.

Podgląd nie wyświetla nic

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

HTTP 500 z komunikatem:

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() i app.UseSession() przed gałęzią middleware 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 błędem Unable to resolve service for type 'IDistributedCache' (aplikacje MVC i Razor Pages rejestrują ją automatycznie).

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 bezpieczeństwa działająca zgodnie z założeniami — zobacz Podstawowe pojęcia → Sesje i bezpieczeństwo.

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.

Serwer działa, ale strona zachowuje się nieprawidłowo — bez żadnych błędów

To są tryby awaryjne, które należy rozważyć najpierw po przeniesieniu aplikacji. Wszystkie trzy pozostawiają serwer w pełni sprawnym, renderują dokument poprawnie i nie generują żadnych komunikatów w konsoli przeglądarki.

Wskaźnik zajętości, który nigdy nie znika. Twoje wywołania zwrotne podglądu są zadeklarowane jako globalne funkcje nazwane po identyfikatorze kontenera — ctlDoc_OnViewerReady() i podobne. Poprzedni podgląd odwoływał się do tych nazw; ten już nie. Obsługa, która powinna ukrywać wskaźnik, po prostu nigdy się nie uruchamia. Przekaż funkcje jako opcje:

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

Dokument ukryty pod wskaźnikiem jest w porządku. Pełna lista opcji znajduje się w KonfiguracjaPodglądu.

Brak ikon podglądu lub elementów interfejsu, pozostałe strony poprawne. ResPath jest pusty lub wskazuje na katalog główny aplikacji — w poprzedniej bibliotece było to poprawne, tutaj nie. Musi określać prefiks, który montuje UseDoconutResources():

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

Uszkodzone kafelki na późniejszych stronach przy serwowaniu z współdzielonego magazynu. Strony, które są jeszcze zapisywane, odpowiadają kodem 202 Accepted. Klient bez retryOn409: true traktuje to jako nieudaną grafikę. Zobacz Rozproszone wdrożenia.

Niepowodzenie otwarcia dokumentu

LicenseException z komunikatem odrzucenia — plik licencji został znaleziony, ale odrzucony (nieprawidłowy podpis, manipulowany, na czarnej liście lub wersja/okno aktualizacji niezgodne z licencją). Ten stan blokuje otwieranie (fail‑fast) zamiast degradacji do znaku wodnego; przeczytaj 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 możliwość ta nie jest już przyznana. 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ę poprzez 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.

Niepowodzenie uruchomienia

InvalidOperationException mentioning a plugin registered via AddPlugin — bieżąca licencja nie‑tymczasowa nie przyznaje tej funkcji 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 natychmiastowa — napraw nieprawidłową ścieżkę.

Błędy kompilacji / zależności

Pakiet nie zostanie zainstalowany wcale — Doconut.NETStandard 26.8.0 celuje w netstandard2.1, więc NuGet odrzuca projekt .NET Framework. To nie jest rozwiązywalny błąd przywracania: .NET Framework nie może konsumować netstandard2.1. Użyj pakietu Doconut.NETFramework zamiast tego.

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

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

Twój projekt przypiął System.Text.Json lub System.Text.Encodings.Web do wersji niższej niż 9.0.x zadeklarowanej przez Doconut.NETStandard. Usuń downgrade i pozwól NuGet przywrócić graf pakietów (System.Text.Json 9.0.0 i System.Text.Encodings.Web 9.0.0 w audytowanym pakiecie 26.8.0).

Ściana błędów kompilacji zaraz po podniesieniu wersji pakietu — to jest oczekiwane. 26.8.0 ma inną powierzchnię API niż 26.7.0, nie jest kompatybilną aktualizacją. Większość błędów to linie using, które przeniesiono do głównej przestrzeni nazw Doconut; przejdź przez Migracja do .NET Standard 2.1 zamiast naprawiać je pojedynczo.

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 przez pakiet). Nie usuwaj ani nie nadpisuj tej zależności — każda próba otwarcia PPT/PPTX/PPS/POT/ODP zakończy się niepowodzeniem bez niej.

Wyjście wygląda niepoprawnie

Strony mają znak wodny — aplikacja znajduje się w stanie ewaluacyjnym: nie znaleziono pliku licencji, wygasło tymczasowe lub subskrypcyjne okno, albo domena jest nieprawidłowa. Sprawdź IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — odwołanie do IDoconutLicenseService na stronie Licensing pokazuje gotowy punkt końcowy.

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

csharp
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);

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

Prezentacje otwierają się, ale nie renderują w Linux/macOS — bieżący renderujący 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

Klasyczna niespodzianka przy 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 ich możliwości są nieobecne. Zarejestrowane wtyczki Converter lub DICOM z niewystarczającą licencją nie‑tymczasową zawodzą podczas AddDoconut(). Porównaj IsCapabilityGranted(...) z każdą funkcją, którą włączasz przed wdrożeniem.

Wyszukiwanie nie znajduje nic (lub za mało)

  • Dla bezpośredniego PDF, AllowSearch nie został włączony w momencie otwarcia. Word, Excel i PowerPoint udostępniają ten sam przełącznik poprzez ich zagnieżdżony PdfConfig.
  • Zawartość jest zeskanowana/tylko obraz, więc zwykłe 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 w ustawieniach domyślnych — ustaw DefaultRender = false, aby renderowały się przez projekcję PDF z natywną warstwą tekstową. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB i MHT wyszukują w swoich domyślnych katalogach.
  • objViewer.CanSearch() jest false po inicjalizacji — rozpoznany format nie ma standardowej ścieżki wyszukiwania. Ten werdykt jest oddzielny od licencji Search; zweryfikuj oba.

Nadal utknąłeś?

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

Czy ta strona była pomocna?