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 é selado, registrado como um serviço transiente 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ões, de modo que descartar o serviço nunca poderia encerrar um documento aberto (veja Conceitos Principais → Como o Visualizador Funciona).

OpenDocumentAsync

Abre um documento e devolve 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 traz o motivo da rejeição), ou o formato requer uma capacidade de plugin que não está mais concedida. 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 — expiração deslizante realiza a mesma limpeza — mas é recomendada para documentos grandes.

GetPageCount

int GetPageCount(string token)

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

DocOptions

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

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

Marca d'água personalizada

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

^Texto~Cor~TamanhoFonte~NomeFonte~Opacidade~Ângulo

string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidencial~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 marca d'água 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 GIF animada recebe marca d'água quadro a quadro. Portanto, uma marca d'água personalizada é um recurso licenciado, não um meio 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 superfície é:

Metadados DICOM

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

O método está presente para alinhamento de API, mas o visualizador DICOM .NET 6 não pode fornecer tags técnicas. Ele devolve null para sessões DICOM e não‑DICOM; em uma sessão DICOM também grava um aviso único explicando a limitação da plataforma. Renderização de página, quadro e animação continuam suportadas.

Auxiliares de recurso — ReferenceCss / ReferenceScripts

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

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

**Flags de CssConfig:** IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss(condicionado por busca),IncludeAnnotationCss` (condicionado por anotação).

**Flags de ScriptConfig:** IncludeJQuery(necessário para todos os demais),IncludeBootstrap, IncludeViewerScripts(núcleo:docViewer.js+ splitter + links),IncludeSearchScriptseIncludeSearchBar(condicionado por busca),IncludeAnnotationScriptseIncludeAnnotationBar` (condicionado 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 }))