Rozwiązywanie problemów
Diagnozowanie typowych błędów
Poniżej znajdują się dosłowne komunikaty Doconut, uporządkowane według objawów. Znajdź swój błąd i zastosuj poprawkę.
Podgląd nie wyświetla nic
Pusty obszar podglądu, konsola przeglądarki pełna 404 dla /doconut-res/...
UseDoconutResources() jest brakujący lub umieszczony po UseDoconut(). Musi być pierwszy w potoku.
Podgląd zgłasza The viewer handler could not be reached (no response).
Żądanie nigdy nie otrzymało odpowiedzi. Częstą przyczyną jest BasePath, który zaczyna się od /: '/doconut' staje się //doconut/DocImage.axd, żądaniem do innego hosta. Napisz je bez początkowego ukośnika (BasePath: 'doconut').
Podgląd zgłasza Please make sure your middleware is configured.
Punkt końcowy strony odpowiedział 404: UseDoconut() nie jest zamontowany tam, gdzie wskazuje BasePath klienta. Z app.Map("/doconut", branch => branch.UseDoconut()), klient używa BasePath: 'doconut'.
HTTP 500 z:
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ą pośrednika 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 Unable to resolve service for type 'IDistributedCache' (aplikacje MVC i Razor Pages rejestrują ją już domyślnie).
Obrazek błędu w obszarze strony z napisem:
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 ponownie uruchomiona (nowe klucze sesji). To warstwa bezpieczeństwa działa zgodnie z zamierzeniami — zobacz Podstawowe koncepcje → Sesje i bezpieczeństwo. Odrzucenie jest obrazkiem zwróconym ze statusem 200, więc monitor sprawdzający tylko kody statusu liczy go jako stronę.
Obrazek błędu z napisem:
Document session not found. Please re-open document.Token wygasł (przesuwane okno, domyślnie 60 minut — DocOptions.TimeOut) lub sesja została zamknięta. Otwórz ponownie dokument, aby uzyskać nowy token.
Serwer działa prawidłowo, ale strona zachowuje się niepoprawnie — bez żadnych błędów
To są tryby awaryjne, które należy rozważyć jako pierwsze po przeniesieniu aplikacji. Wszystkie trzy pozostawiają serwer w pełni sprawnym, prawidłowo renderują dokument i nie zgłaszają nic w konsoli przeglądarki.
Wskaźnik ładowania, który nigdy się nie zatrzymuje.
Twoje wywołania zwrotne podglądu są zadeklarowane jako globalne funkcje nazwane po identyfikatorze kontenera — ctlDoc_OnViewerReady() i podobne. Poprzedni podgląd wyszukiwał te nazwy; ten nie. Obsługa, która miałaby ukryć wskaźnik, po prostu nigdy się nie uruchamia. Przekaż funkcje jako opcje zamiast tego:
function ctlDoc_OnViewerBusy() { /* pokaż swój wskaźnik zajętości */ }
function ctlDoc_OnViewerReady() { /* ukryj go */ }
function ctlDoc_Copy(text) { /* użyj skopiowanego tekstu */ }
function ctlDoc_AutoLoadStatus(pageNum) { /* raportuj postęp */ }
const objViewer = $('#div_ctlDoc').docViewer({
// ... twoje istniejące opcje ...
onViewerBusy: ctlDoc_OnViewerBusy,
onViewerReady: ctlDoc_OnViewerReady,
onCopy: ctlDoc_Copy,
onAutoLoadStatus: ctlDoc_AutoLoadStatus
});Dokument za wskaźnikiem jest w porządku. Pełna lista opcji znajduje się w ViewerConfig.
Brak ikon podglądu lub obramowania, pozostałe strony poprawne.
ResPath jest pusty lub wskazuje na korzeń aplikacji — poprawne w poprzedniej bibliotece, niepoprawne tutaj. Musi podawać prefiks, który UseDoconutResources() montuje:
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ą 202 Accepted. Klient bez retryOn409: true traktuje to jako nieudaną grafikę. Zobacz Distributed Deployments.
Otwieranie dokumentu nie powiodło się
LicenseException z komunikatem odrzucenia — plik licencji został znaleziony, ale odrzucony (nieprawidłowy podpis, zmodyfikowany, na czarnej liście lub wersja poza oknem wersji/aktualizacji licencji). Ten stan blokuje otwieranie (szybkie niepowodzenie) zamiast degradacji do znaku wodnego; przeczytaj License.RejectionMessage po wyjaśnienie.
LicenseException:
This document type requires the 'Dicom' plugin license.Rozszerzenie jest obsługiwane wyłącznie przez wtyczkę (tutaj: DICOM). Wtyczka jest zarejestrowana, ale żadna licencja nie przyznaje już jej możliwości — zazwyczaj tymczasowa licencja, która wygasła po uruchomieniu aplikacji. Zainstaluj licencję, która to umożliwia i zweryfikuj IsCapabilityGranted(LicenseCapability.Dicom) na IDoconutLicenseService. Brak lub niewystarczające uprawnienie nie‑tymczasowe zazwyczaj powoduje błąd wcześniej, podczas AddDoconut().
FormatNotSupportedException:
Document format '<extension>' is not supported.Brak podglądu — wbudowanego, wtyczki ani niestandardowego — który obsługuje to rozszerzenie. Sprawdź listę obsługiwanych formatów; dla własnych formatów DoconutOptions.RegisterViewer może dodać jeden.
InvalidDataException — zawartość pliku jest uszkodzona lub nie pasuje do jego rozszerzenia (np. plik został przemianowany). Zweryfikuj przesyłane pliki przed otwarciem.
InvalidOperationException:
No IDocumentConverter is registered. Add the converter plugin: options.AddPlugin<Doconut.Plugins.Converter.ConverterPlugin>().Rozwiązałeś DocumentConverter bez rejestracji wtyczki Converter.
Uruchamianie nie powiodło się
InvalidOperationException wspominający o wtyczce zarejestrowanej przez AddPlugin — bieżąca licencja nie‑tymczasowa nie przyznaje tej wtyczce możliwości. Usuń rejestrację lub zainstaluj licencję, która to umożliwia. Brak licencji i starszy plik TRIAL nie przyznają żadnych możliwości wtyczek.
ArgumentException z AddDoconut():
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 szybkie‑niepowodzenie — napraw nieprawidłową ścieżkę.
Błędy budowania / zależności
Pakiet nie zostanie zainstalowany wcale — Doconut.NETStandard celuje w netstandard2.1, więc NuGet odrzuca projekt .NET Framework. To nie jest naprawialny 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:
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 poniżej wersji 9.0.x zależności zadeklarowanych 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 zgodnie z deklaracją pakietu).
Ś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 w pierwszym pliku prezentacji:
Could not load ... System.Drawing.Common, Version=6.0.0.0Silnik prezentacji wymaga twardo System.Drawing.Common 6.0.0 (zadeklarowane przez pakiet). Nie usuwaj ani nie nadpisuj tej zależności — każde otwarcie PPT/PPTX/PPS/POT/ODP zakończy się niepowodzeniem bez niej.
Wyjście wygląda niepoprawnie
Strony mają znak wodny — aplikacja jest w stanie ewaluacyjnym: nie znaleziono pliku licencji, wygasła licencja tymczasowa lub nieprawidłowa domena. Przy aktywnej licencji tymczasowej tylko wyjście wtyczki jest znakowane. Kompilacja wydana po dacie subskrypcji płatnej licencji nie ma znaku wodnego: otwarcie zgłasza LicenseException. Sprawdź IDoconutLicenseService (License.IsLicenseFileFound, IsExpired, IsVersionValid, IsValidForDomain, License.RejectionMessage) — odniesienie IDoconutLicenseService na stronie Licencjonowania pokazuje gotowy punkt końcowy.
Starsze dokumenty wyświetlają zniekształcony tekst — kodowania stron kodowych nie są ładowane domyślnie. Dodaj raz przy uruchomieniu:
Encoding.RegisterProvider(CodePagesEncodingProvider.Instance);Nieprawidłowe lub zastąpione czcionki — serwer nie posiada czcionek dokumentu. Zainstaluj je lub skieruj FontFolders (na WordConfig/PptConfig) do folderu, w którym się znajdują.
Adnotacja obrazu wyświetla się w podglądzie, ale eksport ma pole „Image blocked” — host obrazu ma prywatny lub lokalny adres, który serwer odrzuca pobranie. Zobacz Adnotacje.
Funkcja działała w wersji testowej, cicha w produkcji
Klasyczne zaskoczenie przy uruchomieniu: aktywną tymczasową licencję zapewnia wszystkie możliwości; Twoja zakupiona licencja zapewnia tylko to, co kupiłeś. Pakiety wyszukiwania i adnotacji mogą zniknąć, gdy ich możliwości są nieobecne. Zarejestrowany konwerter lub wtyczki DICOM z niewystarczającą nie‑tymczasową licencją zawodzą podczas AddDoconut(). Porównaj IsCapabilityGranted(...) ze wszystkimi funkcjami, które włączasz przed wdrożeniem.
Wyszukiwanie nie znajduje nic (lub za mało)
- Dla bezpośredniego PDF,
AllowSearchnie był włączony w momencie otwarcia. Word, Excel i PowerPoint udostępniają ten sam przełącznik poprzez ich zagnieżdżonePdfConfig. - Zawartość jest skanowana/tylko obraz, więc zwykłe Wyszukiwanie nie ma warstwy tekstowej do dopasowania. Użyj źródła zawierającego tekst lub projekcji PDF, która zachowuje tekst.
- HTML i MS Project (MPP) nie są przeszukiwalne w ustawieniach domyślnych — ustaw
DefaultRender = false, aby renderowały się poprzez projekcję PDF z natywną warstwą tekstową. Word, Excel, PowerPoint, TXT, Visio, e‑mail, EPUB i MHT wyszukują w swoich domyślnych katalogach. objViewer.CanSearch()jestfalsepo inicjalizacji — rozpoznany format nie ma standardowej ścieżki wyszukiwania. Ten werdykt jest oddzielny od licencji Search; zweryfikuj oba.- Strona odczytuje wartość zwracaną przez
objViewer.Search(...)— liczba przychodzi w trzecim argumencie, jako callback.
Nadal utknąłeś?
Izoluj problem przy minimalnej aplikacji Quick Start; jeśli tam się odtworzy, skontaktuj się z pomocą techniczną, podając dokument, Twój Program.cs oraz wynik diagnostyki licencji.
Czy ta strona była pomocna?