Viewer

Viewer (namespace Doconut) je veřejný vstupní bod pro otevírání dokumentů z MVC kontrolerů, stránek Web Forms a handlerů. Jedná se o přechodovou službu vytvořenou pomocí DoconutHost.Initialize; získáte ji tam, kde ji používáte:

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

new Viewer() také funguje, jakmile byla spuštěna DoconutHost.Initialize — získá stejné služby — což umožňuje, aby migrovaný kód ze starého balíčku stále kompiloval. Před Initialize vyvolá InvalidOperationException.

Viewer neukládá žádný stav dokumentu na požadavek a úmyslně neimplementuje IDisposable: relace dokumentů existují nezávisle na ní, takže uvolnění Viewer by nikdy neuzavřelo otevřený dokument (viz Jak funguje Viewer).

OpenDocumentAsync

Otevře dokument a vrátí token relace, který widget používá pro každé další volání. Když je UnsafeMode nastaveno na false (výchozí), token je přidělen ASP.NET relaci aktuálního požadavku — zavolejte jej z požadavku, který má stav relace (viz Relace a zabezpečení).

// 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)));
}

Výjimky, které je třeba ošetřit:

• LicenseException — licence byla nalezena, ale odmítnuta (zpráva obsahuje důvod), nebo formát vyžaduje schopnost pluginu, kterou licence neposkytuje.
• FormatNotSupportedException — žádný prohlížeč neobsluhuje příponu souboru.
• InvalidDataException — obsah je poškozený nebo neodpovídá své příponě.

OpenDocument (synchronous)

Pro kód-behind Web Forms a další kód, který nepoužívá asynchronní stránky:

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ždá metoda vrací token a také jej ukládá do viewer.Token. fileName musí mít správnou příponu. Tyto obálky lze bezpečně volat z stránky Web Forms: cesta otevření se nikdy neobnoví v kontextu ASP.NET požadavku, takže čekání na ni nemůže způsobit zablokování. To neplatí pro každé asynchronní API Doconut — viz sekce Web Forms v Pluginu převodníku.

Zavřít dokument

void CloseDocument(string token)

Odstraní relaci (okamžitě uvolní dokumentový engine), odstraní oprávnění tokenu z ASP.NET relace aktuálního požadavku a zruší token. Volitelné — posuvná expirace provádí stejný úklid — ale je doporučena pro velké dokumenty.

Dotazy na relaci

Každá metoda vyvolá výjimku, pokud je token neznámý nebo vypršel.

Možnosti dokumentu

Per-open, format-independent options (namespace Doconut):

Vlastní vodoznak

DocOptions.Watermark přijímá šest polí oddělených vlnkou. Volitelný úvodní znak ^ požaduje rozložení po všech rozích:

^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 očekává přesně šest polí po volitelném ^. Neplatná definice je nahrazena viditelným textem Invalid Watermark místo tichého zmizení.

Rozhodnutí o licenci

Stejné rozhodnutí platí pro poskytované stránky i pro exporty anotací. Vlastní vodoznak je funkcí licencované aplikace, nikoli způsobem, jak nahradit evaluační vodoznak.

API anotací

Nahrávání a export anotací na straně serveru. Průvodce je v Anotace.

DICOM metadata

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

V tomto balíčku vždy vrací null a požadavek widgetu na metadata odpovídá 501 Not Implemented: čtení DICOM tagů není k dispozici v .NET Framework. DICOM rendering — stránky, rámečky a animace — funguje. Viz DICOM plugin.

Pomocníci zdrojů — ReferenceCss / ReferenceScripts

Vypíše značky <link> a <script> pro zdroje, které modul zdrojů poskytuje pod DoconutOptions.ResourcesPath, v pořadí závislostí. Soubory pro funkce omezené licencí (Search, Annotation) jsou vypisovány pouze když licence umožňuje.

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; }

CssConfig příznaky: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (omezeno vyhledáváním), IncludeAnnotationCss (omezeno anotací).

ScriptConfig příznaky: IncludeJQuery (vyžadováno všemi ostatními), IncludeBootstrap, IncludeViewerScripts (základní skripty prohlížeče), IncludeSearchScripts a IncludeSearchBar (omezeno vyhledáváním), IncludeAnnotationScripts a IncludeAnnotationBar (omezeno anotací).

Obě vrací HTML: zapište je pomocí @Html.Raw(...) v MVC 5 (vytvořte je v kontroleru — pohledy nemají @inject) nebo <%= %> ve Web Forms. Rychlý start ukazuje obojí.

RenderViewer

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

Vrací blok <script>, který inicializuje widget na elementu s id elementId a zobrazí dokument: docViewer({...}) vytvořený z ViewerConfig (výchozí: BasePath: '/', ResPath: 'doconut-res/images'), poté .View(token). Zapište jej po skriptech vieweru. Vygenerovaný skript neuchovává žádnou referenci na objekt vieweru, takže stránka s vlastní lištou by měla widget inicializovat ručně. Viz ViewerConfig.

Web farm

string? AccessToken obsahuje podepsaný tiket vydaný posledním otevřením, když je aktivní distribuovaný režim a UnsafeMode je false; na jediném serveru je null. Pošlete jej widgetu s tokenem: objViewer.View(token, access).