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ążenie | Kiedy 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 |
// 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
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
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
(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
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łonek | Znaczenie |
|---|---|
bool IsSearchEnabled | Obecna licencja przyznaje Search |
bool IsAnnotationEnabled | Obecna 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):
| Typ | Właściwość | Domyślne | Opis |
|---|---|---|---|
string | Password | "" | Hasło do chronionych dokumentów (automatycznie kopiowane do konfiguracji formatu). |
int | ImageResolution | 0 | Przestarzałe. Zachowane wyłącznie dla kompatybilności — zamiast tego ustaw ImageResolution w konfiguracji formatu. |
string | Watermark | "" | 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". |
int | TimeOut | 60 | Przesuwające się wygaśnięcie sesji w minutach. |
bool | IsSecured | true | Obecnie 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:
| Typ | Właściwość | Domyślne | Opis |
|---|---|---|---|
bool | IsWebFarm | false | Przestarzał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. |
string | WebFarmPath | "" | Przestarzałe — nie ma efektu. Użyj FileShareConfig.RootPath, jak opisano w Rozproszone wdrożenia. Poprzednio zapisane jako WebfarmPath. |
bool | EditMode | false | Zarezerwowane 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~Color~FontSize~FontName~Opacity~Anglestring token = await viewer.OpenDocumentAsync(
path,
new PdfConfig(),
new DocOptions
{
Watermark = "^Confidential~Red~24~Verdana~80~-45",
TimeOut = 30
});| Pole | Przykład | Znaczenie |
|---|---|---|
Leading ^ | ^ | Opcjonalny układ na wszystkich rogach. Bez niego używane jest normalne rozmieszczenie znaku wodnego. |
| Text | Confidential | Tekst renderowany na każdej stronie. Nie może być pusty. |
| Color | Red | Nazwana kolor rozumiany przez warstwę rysowania. |
| FontSize | 24 | Rozmiar czcionki; nieprawidłowa wartość numeryczna powoduje użycie domyślnego rozmiaru renderera. |
| FontName | Verdana | Żądana rodzina czcionek. Upewnij się, że jest zainstalowana w środowisku wdrożeniowym. |
| Opacity | 80 | Wartość bajtowa od 0 do 255. Musi zostać poprawnie sparsowana. |
| Angle | -45 | Ką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 licencji | Dostarczona wartość niestandardowa | Wynik renderowania |
|---|---|---|
| Ważna płatna licencja podglądu | Nie | Czysta strona |
| Ważna płatna licencja podglądu | Tak | Niestandardowy znak wodny |
| Aktywny tymczasowy/pokazowy podgląd bazowy | Nie | Czysta strona podglądu bazowego |
| Aktywny tymczasowy/pokazowy podgląd bazowy | Tak | Niestandardowy znak wodny, gdy obowiązuje czysta ścieżka podglądu bazowego |
| Brakująca, odrzucona, wygasła, nieprawidłowa wersja lub licencja nieprawidłowej domeny | Dowolna | Znak wodny wymuszania/ewaluacji; wartość niestandardowa go nie nadpisuje |
| Renderowanie wtyczki zgodnie z zasadami ewaluacji | Dowolna | Znak 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:
| Element | Cel |
|---|---|
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
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.
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).
@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?