Dostosowywanie wydajności

Profil zasobów Doconut jest zdominowany przez trzy elementy: render DPI, co pozostaje w pamięci podręcznej oraz jak długo trwają sesje. Ten przewodnik omawia dźwignie w kolejności ich wpływu.

Rozdzielczość — najważniejsza dźwignia

ImageResolution (25–300 DPI) wpływa zarówno na czas renderowania, jak i rozmiar obrazu. Większość formatów domyślnie używa 200 DPI; obrazy i PSD domyślnie 100.

// A document list preview doesn't need print quality
var token = await viewer.OpenDocumentAsync(path, new PdfConfig { ImageResolution = 100 });

Zmniejszenie DPI o połowę mniej więcej czwarta liczbę pikseli na stronę — szybsze renderowanie, mniejsze transfery, mniej pamięci podręcznej. Zachowaj 250–300 DPI dla zastosowań intensywnie korzystających z powiększenia (CAD, rysunki inżynierskie).

W przypadku plików PDF z dużą ilością osadzonych obrazów, PdfConfig dodaje bardziej precyzyjne ustawienia: CompressImages + CompressQuality, ResizeImages + ResizeResolution oraz CompressFast. Dla zwykłych obrazów, ImageConfig.MaxImagePixelSize (domyślnie 3000 px) ogranicza rozmiar wyjściowy.

Buforowanie stron — pamięć vs. ponowne renderowanie

BaseConfig.CachePages (domyślnie true) przechowuje każdą wyrenderowaną stronę w pamięci przez cały czas trwania sesji. To właściwe ustawienie domyślne dla interaktywnego przeglądania — użytkownicy przewijają w przód i w tył. Wyłącz je, gdy:

• dokumenty są ogromne i przeglądane jednorazowo, od początku do końca,
• wiele równoczesnych sesji pomnożyłoby buforowane strony,
• wolisz zużywać CPU na każde wyświetlenie niż zajmować pamięć RAM.

var token = await viewer.OpenDocumentAsync(path, new PdfConfig { CachePages = false });

Po stronie klienta, ViewerConfig.CacheEnabled = true wstępnie ładuje małe przesuwające się okno nadchodzących obrazów stron w pamięci przeglądarki. Jest to bufor prefetch per-widok, a nie trwałe localStorage.

Sesje — pamięć, której nie widzisz

Każda otwarta sesja przechowuje sparsowany model dokumentu oraz (przy włączonym CachePages) jego wyrenderowane strony, aż do upłynięcia przesuwającego się TimeOut (domyślnie 60 minut) od ostatniego żądania. Dwa nawyki pomagają utrzymać to pod kontrolą:

• Zamknij to, z czego skończyłeś. viewer.CloseDocument(token) zwalnia silnik natychmiast, zamiast czekać na okno bezczynności.
• Dostosuj czas wygaśnięcia. Podgląd, na który użytkownicy patrzą przez dwie minuty, nie wymaga godziny sesji:

var token = await viewer.OpenDocumentAsync(path, new DocOptions { TimeOut = 10 });

Pamiętaj o kompromisie: po wygaśnięciu widżet wyświetla Document session not found. Please re-open document. — wybierz czas wygaśnięcia, który odpowiada rzeczywistym sesjom czytania.

Przełączniki specyficzne dla formatów

• Excel: MemoryOptimizationPreference jest włączone domyślnie i zmniejsza zużycie pamięci przy renderowaniu bardzo dużych skoroszytów — pozostaw je włączone, lub ustaw na false, jeśli chcesz wymienić pamięć na niewielki przyrost szybkości; SheetNames / PrintArea ograniczają renderowanie do istotnych części.
• Tryb przekierowania ma koszt początkowy: DefaultRender = false konwertuje cały dokument na PDF w momencie otwarcia. Zapewnia natywne wyszukiwanie tekstowe, ale przy dokumencie 500‑stronnicowym wywołanie otwarcia niesie tę konwersję — nie włączaj go automatycznie.
• Word/PPT na Linux/Docker: brakujące czcionki powodują wolne odwoływanie się do zapasowych i błędne metryki; wskaż FontFolders na katalog z Twoimi czcionkami.
• Prezentacje na Linux/macOS: pliki PPT/PPTX/PPS/POT/ODP mogą się otworzyć, ale renderowanie przy użyciu bieżącego silnika prezentacji wymaga natywnego libgdiplus oraz przełącznika czasu wykonywania System.Drawing.EnableUnixSupport=true. Inne rodziny formatów korzystają ze standardowej, wieloplatformowej ścieżki renderowania.

Strategie po stronie klienta

• LargeDoc = true — strategia leniwego ładowania dla bardzo dużych dokumentów; strony ładują się w miarę zbliżania się użytkownika.
• AutoLoad = false (domyślnie) — nie renderuj, dopóki nie wywołasz View(token).
• ShowThumbs = false — pomiń generowanie/żądania miniatur dla jednosktroniczych lub osadzonych podglądów.
• Włączenie FixedZoom zapobiega dowolnym zmianom powiększenia; gdy mapujesz C# ViewerConfig, dostosuj FixedZoomPercentMobile (domyślnie 75 w C#) dla małych ekranów.

Inicjalizacja raz, nie przy każdym żądaniu

Encoding.RegisterProvider(CodePagesEncodingProvider.Instance) powinno znajdować się w Program.cs — rejestrowanie kodowań przy każdym żądaniu to zmarnowana praca; całkowite pominięcie tego łamie starsze dokumenty o kodowaniu stron kodowych.

Lista kontrolna dostrajania

1. Ustaw najniższą ImageResolution, jaką akceptuje Twoje UX.
2. Pozostaw CachePages włączone dla interaktywnego przeglądania; wyłącz je w scenariuszach jednorazowego przeglądu lub wysokiej współbieżności.
3. Zamykaj sesje explicite; skróć TimeOut, gdy użycie jest przerywane.
4. Użyj LargeDoc + domyślnego AutoLoad = false po stronie klienta dla dużych dokumentów.
5. Używaj DefaultRender = false tylko wtedy, gdy potrzebujesz PDF‑a zawierającego tekst.