Przeglądarka

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

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

new Viewer() również działa po uruchomieniu DoconutHost.Initialize — rozwiązuje te same usługi — co umożliwia kompilację kodu migrowanego 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 niej, więc zwolnienie Viewer nigdy nie zamknie otwartego dokumentu (zobacz Jak działa Viewer).

OpenDocumentAsync

Otwiera dokument i zwraca token sesji, którego widget używa przy każdym późniejszym żądaniu. Gdy UnsafeMode jest false (wartość domyślna), token jest przydzielany do sesji ASP.NET bieżącego żądania — wywołaj go z żądania, które posiada stan sesji (zobacz Sesje i bezpieczeństwo).

// Simple open
string token = await viewer.OpenDocumentAsync(path);

// With per-format config and options
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// From an upload (HttpPostedFileBase in MVC; HttpPostedFile in 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 — znaleziono licencję, ale została 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 swojego rozszerzenia.

OpenDocument (synchroniczny)

Dla kodu w Web Forms i innych scenariuszy, które nie używają stron asynchronicznych:

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żda metoda zwraca token i dodatkowo zapisuje go w viewer.Token. fileName musi zawierać właściwe 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 nie jest prawdą dla każdej asynchronicznej API Doconut — zobacz sekcję Web Forms w Wtyczka konwertera.

CloseDocument

void CloseDocument(string token)

Usuwa sesję (natychmiast zwalniając silnik dokumentu), usuwa przyznanie tokenu z bieżącej sesji ASP.NET żądania i unieważnia token. Opcjonalnie — wygaśnięcie przesuwane wykonuje tę samą czynność czyszczenia — ale zalecane przy dużych dokumentach.

Zapytania sesji

Każda metoda zgłasza wyjątek, jeśli token jest nieznany lub wygasł.

DocOptions

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

Niestandardowy znak wodny

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

^Text~Color~FontSize~FontName~Opacity~Angle

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });

Parser oczekuje dokładnie sześciu pól po opcjonalnym ^. Nieprawidłowa definicja zostaje zastąpiona widocznym tekstem Invalid Watermark zamiast zniknąć cicho.

Decyzja licencyjna

Ta sama decyzja dotyczy 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. Szczegółowy opis znajduje się w Adnotacje.

Metadane DICOM

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. DICOM renderowanie — strony, klatki i animacje — działa. Zobacz Wtyczka DICOM.

Pomocnicze zasoby — ReferenceCss / ReferenceScripts

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

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // license state, for guarding ribbon init code
bool IsAnnotationEnabled { get; }

Flagi CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (dostępne po wyszukiwaniu), IncludeAnnotationCss (dostępne po adnotacji).

Flagi ScriptConfig: IncludeJQuery (wymagane przez wszystkie pozostałe), IncludeBootstrap, IncludeViewerScripts (główne skrypty podglądu), IncludeSearchScripts i IncludeSearchBar (dostępne po wyszukiwaniu), IncludeAnnotationScripts i IncludeAnnotationBar (dostępne po adnotacji).

Obie 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 rozwiązania.

RenderViewer

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 na podstawie 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 ViewerConfig.

Farma serwerowa

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