Przeglądarka

Główna klasa przeglądarki dokumentów

Viewer (namespace Doconut) jest publicznym punktem wejścia do otwierania dokumentów z kontrolerów MVC, stron Web Forms i obsługujących handlerów. Jest to usługa przejściowa skomponowana przez DoconutHost.Initialize; rozwiąż ją tam, gdzie jej używasz:

csharp
var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() działa również po uruchomieniu DoconutHost.Initialize — rozwiązuje te same usługi — co pozwala na kompilację kodu przeniesionego z klasycznego pakietu. Przed Initialize, zgłasza InvalidOperationException.

Viewer nie przechowuje stanu dokumentu per żądanie i celowo nie implementuje IDisposable: sesje dokumentów istnieją niezależnie od niego, więc zwolnienie Viewer nigdy nie zamknie otwartego dokumentu (zobacz How the Viewer Works).

OpenDocumentAsync

Otwiera dokument i zwraca token sesji, którego widżet używa przy każdym późniejszym żądaniu. Gdy UnsafeMode jest false (domyślnie), token jest przydzielany do sesji ASP.NET bieżącego żądania — wywołaj go z żądania, które ma stan sesji (zobacz Sessions & Security).

PrzeciążenieKiedy używać
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Otwieranie z dysku z automatycznym wykrywaniem formatu i domyślną konfiguracją formatu
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Potrzebujesz opcji renderowania per format (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)Dokument nie jest plikiem na dysku (przesyłanie, baza danych, blob). fileInfo musi mieć odpowiednie rozszerzenie — wybiera format
csharp
// Proste otwarcie
string token = await viewer.OpenDocumentAsync(path);

// Z konfiguracją i opcjami dla każdego formatu
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// Z przesłania (HttpPostedFileBase w MVC; HttpPostedFile w Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

Wyjątki do obsłużenia:

  • LicenseException — licencja została znaleziona, ale odrzucona (wiadomość zawiera przyczynę), lub format wymaga możliwości wtyczki, której licencja nie przyznaje.
  • FormatNotSupportedException — żaden podgląd nie obsługuje rozszerzenia pliku.
  • InvalidDataException — zawartość jest uszkodzona lub nie pasuje do jej rozszerzenia.

OpenDocument (synchronous)

Dla kodu zaplecza Web Forms i innego kodu, który nie używa stron asynchronicznych:

text
string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

Każdy zwraca token i dodatkowo przechowuje go w viewer.Token. fileName musi mieć odpowiednie rozszerzenie. Te opakowania są bezpieczne do wywołania z strony Web Forms: ścieżka otwarcia nigdy nie wznawia się w kontekście żądania ASP.NET, więc oczekiwanie na nią nie może spowodować zakleszczenia. To samo nie dotyczy każdego asynchronicznego API Doconut — zobacz sekcję Web Forms w Converter Plugin.

Zamknij dokument

text
void CloseDocument(string token)

Usuwa sesję (natychmiast zwalniając silnik dokumentu), usuwa przyznanie tokenu z sesji ASP.NET bieżącego żądania i unieważnia token. Opcjonalnie — wygasanie przesuwne wykonuje tę samą operację czyszczenia — ale zalecane jest dla dużych dokumentów.

Zapytania sesji

CzłonekZwraca
int GetPageCount(string token)Łączna liczba stron otwartego dokumentu
(int Width, int Height) GetPageDimensions(string token, int page = 1)Domyślny rozmiar renderowanej strony przy 100 % powiększeniu — przestrzeń współrzędnych dla adnotacji tworzonych w kodzie
IReadOnlyList<string> GetWorksheetNames(string token)Renderowane arkusze kalkulacyjne, w kolejności skoroszytu; puste dla innych dokumentów

Każde zgłasza InvalidOperationException (Document session not found. Please re-open document.), jeśli token jest nieznany lub wygasł, oraz ArgumentException dla pustego tokenu.

Opcje dokumentu

Opcje niezależne od formatu, obowiązujące przy otwarciu (przestrzeń nazw Doconut):

TypWłaściwośćDomyślneOpis
stringPassword""Hasło do chronionych dokumentów (automatycznie kopiowane do konfiguracji formatu).
stringWatermark""Niestandardowy tekst znaku wodnego rysowany na renderowanych stronach — patrz poniżej.
intTimeOut60Przesuwne wygasanie sesji, w minutach.
stringBrowserId""Farmy sieciowe: przeglądarka, do której przypisany jest podpisany bilet. Ustaw ją za pomocą DoconutFarmBinding.EnsureBrowserId (zobacz Sesje i bezpieczeństwo).
stringUserId""Farmy sieciowe: zalogowany użytkownik, do którego przypisany jest bilet, pochodzący z DoconutFarmBinding.ResolveUserId.
intImageResolution0Przestarzałe. Ustaw ImageResolution w konfiguracji formatu zamiast tego.
boolIsSecuredtrueZarezerwowane; nie wymuszane. Kontrola dostępu to DoconutOptions.UnsafeMode.
boolIsWebFarm / string WebFarmPathfalse / ""Zachowane dla kodu migrowanego z klasycznego pakietu. Nie włączają trybu farmy — AddDoconutDistributed robi.
boolEditModefalseZarezerwowane dla oddzielnie dystrybuowanego edytora; pozostaw false.

Niestandardowy znak wodny

DocOptions.Watermark przyjmuje sześć pól oddzielonych tyldą. Opcjonalny wiodący ^ żąda układu we wszystkich rogach:

text
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
PolePrzykładZnaczenie
Leading ^^Opcjonalny układ we wszystkich rogach. Bez niego używane jest normalne rozmieszczenie.
TextConfidentialTekst rysowany na każdej stronie. Nie może być pusty.
ColorRedNazwany kolor.
FontSize24Rozmiar czcionki; nieprawidłowa wartość numeryczna powoduje powrót do domyślnego.
FontNameVerdanaRodzina czcionek. Musi być zainstalowana na serwerze — Windows Server ma mniej czcionek niż komputer stacjonarny.
Opacity800 do 255. Musi dawać się sparsować.
Angle-45Obrót w stopniach; nieprawidłowa wartość numeryczna powoduje powrót do domyślnego.

Parser oczekuje dokładnie sześciu pól po opcjonalnym ^. Nieprawidłowa definicja jest zastępowana widocznym tekstem Invalid Watermark zamiast cichego zniknięcia.

Decyzja licencyjna

Stan licencjiDostarczona wartość niestandardowaWynik renderowania
Ważna płatna licencja przeglądarkiNieCzysta strona
Ważna płatna licencja przeglądarkiTakNiestandardowy znak wodny
Aktywna tymczasowa/licencja demonstracyjnaNieCzysta strona
Aktywna tymczasowa/licencja demonstracyjnaTakNiestandardowy znak wodny
Brakująca, odrzucona, wygasła, nieprawidłowa wersja lub licencja nieprawidłowej domenyObieZnak wodny ewaluacyjny; wartość niestandardowa go nie zastępuje

Ta sama decyzja ma zastosowanie do serwowanych stron oraz eksportów adnotacji. Niestandardowy znak wodny jest funkcją licencjonowanej aplikacji, a nie sposobem na zastąpienie znaku wodnego ewaluacyjnego.

API adnotacji

Ładowanie i eksport adnotacji po stronie serwera. Przewodnik znajduje się w Adnotacje.

CzłonekCel
AnnotationManager GetAnnotationManager(string token)Menedżer powiązany z wymiarami strony otwartej sesji
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Menedżer z wyraźnie określonymi wymiarami strony
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Menedżer niezależny od sesji
void LoadAnnotationData(string token, AnnotationManager manager)Wczytaj adnotacje stworzone w C# do sesji
void LoadAnnotationData(string token, string annotationData)Wczytaj zakodowaną kopertę zwróconą przez AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Wczytaj adnotacje z XML
XmlDocument GetAnnotationXML(string token)Eksportuj adnotacje sesji jako XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF z wtopionymi adnotacjami
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)Jeden PNG na stronę, adnotacje wtopione, zapisane do directoryPath (utworzone, jeśli brak); zwraca liczbę zapisanych obrazów
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ZIP z PNG‑ami per strona z wtopionymi adnotacjami

Metadane DICOM

text
Task<DicomMetadata?> GetDicomMetadataAsync(string token, CancellationToken ct = default)

W tym pakiecie zawsze zwraca null, a żądanie metadanych widżetu odpowiada 501 Not Implemented: odczyt tagów DICOM nie jest dostępny w .NET Framework. Renderowanie DICOM — strony, klatki i animacje — działa. Zobacz Wtyczka DICOM.

Pomocnicy zasobów — ReferenceCss / ReferenceScripts

Emituj tagi <link> i <script> dla zasobów, które moduł zasobów udostępnia pod DoconutOptions.ResourcesPath, w kolejności zależności. Pliki funkcji zabezpieczonych licencją (Search, Annotation) są emitowane tylko gdy licencja je przyznaje.

text
string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + przeglądarka + wyszukiwanie + adnotacja
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // stan licencji, w celu ochrony kodu inicjalizacji wstążki
bool IsAnnotationEnabled { get; }

Flagi CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (search-gated), IncludeAnnotationCss (annotation-gated).

Flagi ScriptConfig: IncludeJQuery (required by all others), IncludeBootstrap, IncludeViewerScripts (the core viewer scripts), IncludeSearchScripts i IncludeSearchBar (search-gated), IncludeAnnotationScripts i IncludeAnnotationBar (annotation-gated), EmitFeatureFlags (default true: also writes an inline window.Doconut.features = { search, annotation, editor } script; set it to false under a Content-Security-Policy that blocks inline script).

Oba zwracają HTML: zapisz je przy użyciu @Html.Raw(...) w MVC 5 (generuj je w kontrolerze — widoki nie mają @inject) lub <%= %> w Web Forms. Szybki start pokazuje oba.

RenderViewer

text
string RenderViewer(string elementId, string token, ViewerConfig? config = null)

Zwraca blok <script>, który inicjalizuje widżet na elemencie o identyfikatorze elementId i wyświetla dokument: docViewer({...}) zbudowany z ViewerConfig (domyślnie: BasePath: '/', ResPath: 'doconut-res/images'), a następnie .View(token). Umieść go po skryptach podglądu. Wygenerowany skrypt nie przechowuje odniesienia do obiektu podglądu, więc strona z własnym paskiem narzędzi powinna ręcznie zainicjować widżet. Zobacz KonfiguracjaPodglądu.

Farma sieciowa

string? AccessToken przechowuje podpisany bilet wydany przy ostatnim otwarciu, gdy tryb rozproszony jest aktywny i UnsafeMode jest false; jest null na pojedynczym serwerze. Wyślij go do widżetu wraz z tokenem: objViewer.View(token, accessToken).

Czy ta strona była pomocna?