Rurociąg renderowania

Pomiędzy OpenDocumentAsync a PNG, które dociera do przeglądarki, istnieją dwa odrębne etapy: rozwiązywanie podglądu (który silnik ładuje dokument, ustalane raz przy otwarciu) i przetwarzanie stron (co dzieje się z każdym obrazem strony przy każdym żądaniu). Znajomość obu wyjaśnia, dlaczego format renderuje się w określony sposób — i co naprawdę przełącza DefaultRender.

Etap 1 — Rozwiązywanie podglądu formatu

Fabryka mapuje rozszerzenie pliku na podgląd za pośrednictwem katalogu formatów, z trzema poziomami priorytetu:

1. Niestandardowe podglądy najpierw. Wszystko, co zarejestrowałeś przy użyciu DoconutOptions.RegisterViewer(extension, factory, defaultConfig?), wygrywa nad wszystkimi wbudowanymi.
2. Wbudowane podglądy rodzinne. Katalog mapuje każde rozszerzenie możliwe do wyświetlenia na rodzinę podglądów — Word, Excel, PowerPoint, Pdf, Cad, Dgn, Image, Tiff, Psd, Email, Visio, Project, Xps, Epub, Txt, Html, Mht, Dcn — każda z własnym adapterem silnika. Jeśli licencjonowana wtyczka dostarcza podgląd dla tego samego rozszerzenia, podgląd wtyczki zastępuje wbudowany. AddDoconut() weryfikuje zarejestrowane uprawnienia wtyczek przy uruchomieniu; domyślne przejście fabryki do wbudowanego podglądu jest defensywną regułą w czasie działania.
3. Formaty tylko wtyczkowe. Niektóre rozszerzenia nie mają w ogóle wbudowanego podglądu — DICOM (.dcm) istnieje wyłącznie poprzez wtyczkę DICOM. Otwarcie takiego bez wymaganego uprawnienia generuje wyjątek:

LicenseException: This document type requires the 'Dicom' plugin license.

Rozszerzenie, które nie ma przypisanego podglądu, powoduje:

FormatNotSupportedException: Document format '<extension>' is not supported.

Po rozwiązaniu, konfiguracja zostaje ustalona: Twój jawnie podany obiekt konfiguracji, jeśli go przekazałeś, w przeciwnym razie domyślna konfiguracja formatu z katalogu. DocOptions.Password jest kopiowane do konfiguracji dla chronionych dokumentów.

Etap 1b — Tryb przekierowania (DefaultRender = false)

Większość konfiguracji per-format udostępnia flagę DefaultRender. Wybiera ona pomiędzy dwiema zasadniczo różnymi ścieżkami:

• DefaultRender = true — dokument renderuje się natywnie, bezpośrednio do obrazów stron.
• DefaultRender = false — dokument jest najpierw konwertowany do PDF w pamięci, silnik źródłowy jest zwalniany, a podgląd PDF przejmuje kontrolę. Wygenerowany PDF zawiera rzeczywisty tekst, więc pełnotekstowe wyszukiwanie uzyskuje pikselowo dokładne natywne podświetlenia; rurociąg wymusza włączenie AllowSearch i AllowCopy dla przekierowanego PDF, ponieważ konwersja jest niewidoczna dla użytkownika.

XPS oraz domyślne ustawienie katalogu dla MHT używają ścieżki przekierowania. Projekcja PDF może zapewnić natywne wyszukiwanie dla formatów takich jak HTML i Microsoft Project. Jeśli wynikowy PDF zawiera obrazy bez warstwy tekstowej, standardowy podgląd nie może przeszukiwać tych pikseli.

Używaj trybu przekierowania, gdy potrzebujesz projekcji PDF zawierającej tekst — kosztem wstępnej konwersji przy otwieraniu dokumentu.

Etap 2 — Rurociąg obrazów stron

Renderowane strony są przetwarzane przy każdym żądaniu według ustalonej kolejności:

raw page PNG → watermark → rotate/flip → scale → annotation burn → PNG to the response

• Znak wodny — stosowany w zależności od stanu licencji (brak licencji, wygasła tymczasowa lub subskrypcyjna, nieprawidłowa domena, nieprawidłowa wersja) oraz z DocOptions.Watermark dla własnego niestandardowego tekstu. Poprawnie licencjonowana aplikacja — lub aktywna licencja tymczasowa — bez własnego znaku wodnego pomija ten krok.
• Obrót/odbicie — stan per‑strona ustawiany przez użytkownika w widżecie (90°/180°/270°, odbicia poziome/pionowe) jest przechowywany w sesji i stosowany przy każdym kolejnym renderowaniu tej strony.
• Skalowanie — miniatury i poziomy powiększenia są tworzone przez skalowanie renderowanej strony do żądanego rozmiaru docelowego; 0 oznacza serwowanie w oryginalnym rozmiarze.
• Wypalenie adnotacji — zapisane adnotacje są rysowane na bitmapie, aby eksporty i obrazy stron je wyświetlały.
• Kodowanie — wynik jest kodowany do PNG przy użyciu puli strumieni pamięci i zapisywany bezpośrednio w odpowiedzi HTTP.

Błędy w middleware są zwracane jako obrazy błędów PNG (czerwony tekst na białym tle) zamiast stron błędów HTTP, aby widżet mógł je wyświetlić w obszarze strony.

Buforowanie stron

BaseConfig.CachePages (domyślnie true) przechowuje renderowane obrazy stron w pamięci przez cały czas trwania sesji dokumentu, więc ponowne odwiedzenie strony nie powoduje jej ponownego renderowania. BaseConfig.ImageResolution (25–300 DPI, 0 = domyślne dla formatu) jest głównym pokrętłem jakości/pamięci; domyślne ustawienie każdego formatu jest udokumentowane na jego stronie konfiguracji.

Gdzie dostroić co