Viewer

Główna klasa przeglądarki dokumentów

Viewer (namespace Doconut) jest publicznym punktem wejścia do otwierania dokumentów z Razor pages, kontrolerów MVC, komponentów Blazor lub minimalnych API. Jest sealed, zarejestrowany jako usługa transient przez AddDoconut() i rozwiązywany poprzez wstrzykiwanie przez konstruktor — nigdy nie twórz go bezpośrednio.

Poprzednia biblioteka .NET Standard udostępniała publiczny konstruktor przyjmujący pamięciowy cache, dostęp do kontekstu HTTP oraz jedną lub więcej ścieżek licencji. Ten konstruktor został usunięty; graf usług dostarcza te zależności.

Viewer nie przechowuje stanu per‑request i celowo nie implementuje IDisposable: sesje dokumentów istnieją niezależnie w pamięci podręcznej sesji, więc zwolnienie usługi nigdy nie zamknie otwartego dokumentu (zobacz Podstawowe pojęcia → Jak działa Viewer).

OpenDocumentAsync

Otwiera dokument i zwraca token sesji, którego widget kliencki używa we wszystkich kolejnych żądaniach. Każde otwarcie jest asynchroniczne — nie istnieje synchroniczny OpenDocument.

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 (upload, baza danych, blob). fileInfo musi zawierać prawidłowe rozszerzenie — to napędza wykrywanie formatu
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 przesyłania
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Wyjątki do obsłużenia:

  • LicenseException — znalezioną licencję odrzuca się (wiadomość zawiera przyczynę odrzucenia) lub format wymaga możliwości wtyczki, która nie jest już przyznana. Wygaśnięcie kalendarza bez komunikatu o odrzuceniu skutkuje renderowaniem z znakiem wodnym zamiast wyrzucenia wyjątku.
  • FormatNotSupportedException — Document format '<extension>' is not supported.
  • InvalidDataException — zawartość pliku jest uszkodzona lub nie pasuje do jego rozszerzenia.

CloseDocument

text
void CloseDocument(string token)

Usuwa sesję z pamięci podręcznej (natychmiast zwalnia silnik dokumentu), usuwa znacznik bezpieczeństwa i cofa przyznany dostęp. Opcjonalnie — wygasanie przesuwne wykonuje tę samą czynność czyszczenia — ale jest zalecane dla dużych dokumentów.

GetPageCount

text
int GetPageCount(string token)

Łączna liczba stron otwartej sesji. Rzuca InvalidOperationException (Document session not found. Please re-open document.) jeśli token jest nieznany lub wygasł, oraz ArgumentException dla pustego tokenu.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

Domyślny rozmiar renderowanej strony dokumentu przy 100 % powiększeniu — przestrzeń współrzędnych dla adnotacji tworzonych w kodzie. page jest akceptowane dla kompatybilności; wynik to domyślna wartość dokumentu. Rzuca InvalidOperationException (Document session not found. Please re-open document.) jeśli token jest nieznany lub wygasł, oraz ArgumentException dla pustego tokenu.

GetWorksheetNames

text
IReadOnlyList<string> GetWorksheetNames(string token)

Zwraca nazwy arkuszy otwartego arkusza kalkulacyjnego, w kolejności skoroszytu, lub pustą listę, gdy otwarty dokument nie jest arkuszem kalkulacyjnym.

Wymienione są tylko renderowane arkusze: ukryte i puste arkusze są pomijane, a gdy ExcelConfig.SheetNames ogranicza renderowanie, pojawiają się tylko te arkusze. Arkusz nie zawsze mieści się na jednej stronie — bardzo duży jest renderowany na kilku stronach. Rzuca InvalidOperationException (Document session not found. Please re-open document.), jeśli token jest nieznany lub wygasł, oraz ArgumentException dla pustego tokenu.

Dodano w wersji 26.9.0.

Flagi możliwości

CzłonekZnaczenie
bool IsSearchEnabledObecna licencja przyznaje Search
bool IsAnnotationEnabledObecna licencja przyznaje Annotation

Użyj ich w widoku Razor, aby renderować licencjonowany Ribbon tylko wtedy, gdy serwer rzeczywiście go udostępni — zobacz Szybki start.

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).
intImageResolution0Przestarzałe. Zachowane wyłącznie dla kompatybilności — zamiast tego ustaw ImageResolution w konfiguracji formatu.
stringWatermark""Niestandardowy tekst znaku wodnego rysowany na renderowanych stronach. Łańcuch formatowy: "^Text~Color~FontSize~FontName~Opacity~Angle", np. "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Przesuwające się wygaśnięcie sesji w minutach.
boolIsSecuredtrueObecnie nie egzekwowane — zarezerwowane. Powiązanie tokenu jest kontrolowane globalnie przez DoconutOptions.UnsafeMode (zobacz Podstawowe pojęcia → Sessions & Security).

Klasa udostępnia również specjalistyczne właściwości, które są celowo poza normalnym przepływem wyświetlania w pojedynczym hoście:

TypWłaściwośćDomyślneOpis
boolIsWebFarmfalsePrzestarzałe — nie ma efektu. Opublikuj dokument z DistributedDocumentPublisher.PublishAsync (lub IDistributedPublishQueue.EnqueueAsync) i zamiast tego ustaw FileShareConfig.RootPath. Zwróć uwagę na wielkość liter — poprzednia biblioteka zapisywała to jako IsWebfarm.
stringWebFarmPath""Przestarzałe — nie ma efektu. Użyj FileShareConfig.RootPath, jak opisano w Rozproszone wdrożenia. Poprzednio zapisane jako WebfarmPath.
boolEditModefalseZarezerwowane dla oddzielnie dystrybuowanego przepływu edycji; pozostaw false dla standardowego przeglądarki.

Niestandardowy znak wodny

DocOptions.Watermark używa sześciu pól oddzielonych tyldą. Opcjonalny wiodący ^ żąda układu na 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 na wszystkich rogach. Bez niego używane jest normalne rozmieszczenie znaku wodnego.
TextConfidentialTekst renderowany na każdej stronie. Nie może być pusty.
ColorRedNazwana kolor rozumiany przez warstwę rysowania.
FontSize24Rozmiar czcionki; nieprawidłowa wartość numeryczna powoduje użycie domyślnego rozmiaru renderera.
FontNameVerdanaŻądana rodzina czcionek. Upewnij się, że jest zainstalowana w środowisku wdrożeniowym.
Opacity80Wartość bajtowa od 0 do 255. Musi zostać poprawnie sparsowana.
Angle-45Kąt obrotu w stopniach; nieprawidłowa wartość numeryczna powoduje użycie domyślnego.

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

Decyzja licencyjna

Stan licencjiDostarczona wartość niestandardowaWynik renderowania
Ważna płatna licencja podgląduNieCzysta strona
Ważna płatna licencja podgląduTakNiestandardowy znak wodny
Aktywny tymczasowy/pokazowy podgląd bazowyNieCzysta strona podglądu bazowego
Aktywny tymczasowy/pokazowy podgląd bazowyTakNiestandardowy znak wodny, gdy obowiązuje czysta ścieżka podglądu bazowego
Brakująca, odrzucona, wygasła, nieprawidłowa wersja lub licencja nieprawidłowej domenyDowolnaZnak wodny wymuszania/ewaluacji; wartość niestandardowa go nie nadpisuje
Renderowanie wtyczki zgodnie z zasadami ewaluacjiDowolnaZnak wodny ewaluacji

Ta sama decyzja jest stosowana do serwowanych obrazów stron i eksportów adnotacji. Wyjście w formacie animowanego GIF jest znakowane klatka po klatce. Niestandardowy znak wodny jest więc funkcją licencjonowaną aplikacji, a nie sposobem na zastąpienie lub ukrycie znaku wodnego ewaluacji.

API adnotacji

Ładowanie i eksport adnotacji po stronie serwera. Pełny przewodnik znajduje się w Przewodnikach → Adnotacje; interfejs to:

ElementCel
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 adnotacje z zakodowanej strony/envelopy Base64 zwróconej 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

Każdy z nich przyjmuje token sesji. Kształt GetAnnotationManager(pageWidth, pageHeight) wolny od sesji w poprzedniej bibliotece pozostaje dostępny do budowania adnotacji poza sesją, ale ich ładowanie nadal wymaga tokenu.

Metadane DICOM

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

Metoda jest dostępna w celu dopasowania API, ale ten pakiet nie może dostarczyć technicznych tagów DICOM: czytnik metadanych jest dostępny tylko w wersji .NET 8. Zwraca null dla sesji DICOM i nie‑DICOM; w sesji DICOM dodatkowo zapisuje jednorazowe ostrzeżenie wyjaśniające ograniczenie platformy. Renderowanie stron, klatek i animacji pozostaje wspierane.

Pomocnicze zasoby — ReferenceCss / ReferenceScripts

Emituj tagi <link>/<script> dla osadzonych zasobów serwowanych przez UseDoconutResources(), w prawidłowej kolejności zależności. Pakiety dla funkcji ograniczonych licencją, takich jak wyszukiwanie i adnotacje, są emitowane tylko gdy licencja je umożliwia, zachowując spójność interfejsu klienta z zachowaniem serwera.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + przeglądarka + wyszukiwanie + adnotacja
string ReferenceScripts(ScriptConfig? config = null)

Flagi CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (ograniczone wyszukiwaniem), IncludeAnnotationCss (ograniczone adnotacjami).

Flagi ScriptConfig: IncludeJQuery (wymagane przez wszystkie pozostałe), IncludeBootstrap, IncludeViewerScripts (rdzeń: docViewer.js + splitter + links), IncludeSearchScripts i IncludeSearchBar (ograniczone wyszukiwaniem), IncludeAnnotationScripts i IncludeAnnotationBar (ograniczone adnotacjami), EmitFeatureFlags (domyślnie true: zapisuje także wbudowany skrypt window.Doconut.features = { search, annotation, editor }; ustaw na false w ramach Content‑Security‑Policy, które blokuje wbudowane skrypty).

html
@inject Doconut.Viewer Viewer

@Html.Raw(Viewer.ReferenceCss(new CssConfig { IncludeBootstrapCss = true, IncludeViewerCss = true }))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig { IncludeJQuery = true, IncludeViewerScripts = true }))

Te pomocniki są wspieranym sposobem dostarczania zasobów przeglądarki. Aplikacje, które skopiowały docViewer.js, documentLinks.js i docViewer.UI.js do wwwroot, powinny usunąć te kopie, gdy strona zostanie wyrenderowana z emitowanych tagów.

Czy ta strona była pomocna?