Visualizador

Viewer (namespace Doconut) é o ponto de entrada público para abrir documentos a partir de páginas Razor, controladores MVC, componentes Blazor ou APIs mínimas. Ele é sealed, registrado como um serviço transient por AddDoconut(), e resolvido via injeção de construtor — nunca o construa diretamente.

Viewer não mantém estado por requisição e intencionalmente não implementa IDisposable: as sessões de documento vivem independentemente no cache de sessão, de modo que descartar o serviço nunca poderia encerrar um documento aberto (veja Conceitos Principais → Como o Viewer Funciona).

OpenDocumentAsync

Abre um documento e retorna o token de sessão que o widget cliente usa para todas as solicitações subsequentes.

// 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
await using var ms = new MemoryStream();
await file.CopyToAsync(ms);
ms.Position = 0;
token = await viewer.OpenDocumentAsync(ms, new FileInfo(file.FileName));

Exceções a tratar:

• LicenseException — uma licença encontrada é rejeitada (a mensagem contém o motivo da rejeição), ou o formato necessita de um recurso de plugin que não está mais concedido. Expiração de calendário sem mensagem de rejeição reverte para renderização com marca d'água em vez de lançar exceção.
• FormatNotSupportedException — Document format '<extension>' is not supported.
• InvalidDataException — o conteúdo do arquivo está corrompido ou não corresponde à sua extensão.

CloseDocument

void CloseDocument(string token)

Remove a sessão do cache (descartando o motor de documento imediatamente), exclui o marcador de segurança e revoga a concessão de acesso. Opcional — a expiração deslizante realiza a mesma limpeza — mas é recomendada para documentos grandes.

GetPageCount

int GetPageCount(string token)

Total de páginas da sessão aberta. Lança exceção se o token for desconhecido ou expirado.

DocOptions

Opções por abertura, independentes de formato (namespace Doconut):

A classe também expõe propriedades especializadas que estão intencionalmente fora do fluxo normal de visualização de host único:

Custom watermark

DocOptions.Watermark usa seis campos separados por til (~). Um ^ opcional no início solicita o layout em todos os cantos:

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

O analisador espera exatamente seis campos após o ^ opcional. Uma definição inválida é substituída pela alternativa visível Invalid Watermark do SDK em vez de desaparecer silenciosamente.

Decisão de Licença

A mesma decisão é aplicada às imagens de página servidas e às exportações de anotações. A saída de GIF animado é carimbada quadro a quadro. Uma marca d'água personalizada é, portanto, um recurso de aplicação licenciado, não uma forma de substituir ou suprimir a marca d'água de avaliação.

API de Anotações

Carregamento e exportação de anotações no lado do servidor. O tutorial completo está em Guias → Anotações; a interface é:

Metadados DICOM

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

Retorna metadados de tags DICOM para sessões abertas através do plugin DICOM; null para documentos que não são DICOM.

Auxiliares de Recursos — ReferenceCss / ReferenceScripts

Emite as tags <link>/<script> para os recursos incorporados servidos por UseDoconutResources(), na ordem correta de dependência. Pacotes para recursos controlados por licença, como busca e anotação, são emitidos somente quando a licença os habilita, mantendo a interface do cliente consistente com o comportamento do servidor.

string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)

Sinalizadores de CssConfig: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (controlado por busca), IncludeAnnotationCss (controlado por anotação).

Sinalizadores de ScriptConfig: IncludeJQuery (necessário para todos os outros), IncludeBootstrap, IncludeViewerScripts (núcleo: docViewer.js + splitter + links), IncludeSearchScripts e IncludeSearchBar (controlado por busca), IncludeAnnotationScripts e IncludeAnnotationBar (controlado por anotação).

@inject Doconut.Viewer Viewer

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