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. É sealed, registrado como um serviço transient por AddDoconut(), e resolvido via injeção de construtor — nunca o construa diretamente.

A biblioteca .NET Standard anterior expunha um construtor público que recebia o cache de memória, o acessador de contexto HTTP e um ou mais caminhos de licença. Esse construtor foi removido; o grafo de serviços fornece essas dependências.

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 componente cliente usa em todas as solicitações subsequentes. Cada abertura é assíncrona — não existe um OpenDocument síncrono.

// 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 requer uma capacidade de plugin que não é 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)

Remova a sessão do cache (descartando o motor de documento imediatamente), exclua o marcador de segurança e revogue a concessão de acesso. Opcional — a expiração deslizante realiza a mesma limpeza — mas recomendado 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.

Capability flags

Use esses valores em uma visualização Razor para renderizar uma Ribbon licenciada somente quando o servidor realmente a disponibilizará — veja Início Rápido.

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 em 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:

^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 GIF animado é carimbada quadro a quadro. Portanto, uma marca d'água personalizada é um recurso licenciado da aplicação, 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 é:

Cada um desses recebe o token da sessão. A forma sem sessão da biblioteca anterior GetAnnotationManager(pageWidth, pageHeight) ainda existe para criar anotações fora de uma sessão, mas carregá‑las ainda requer um token.

Metadados DICOM

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

O método está presente para alinhamento da API, mas este pacote não pode fornecer tags técnicas DICOM: o leitor de metadados é distribuído apenas em uma compilação .NET 8. Ele retorna null para sessões DICOM e não‑DICOM; em uma sessão DICOM ele também grava um aviso único explicando a limitação da plataforma. A renderização de página, quadro e animação continua suportada.

Auxiliares de recurso — ReferenceCss / ReferenceScripts

Emita 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 pesquisa 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)

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (controlado por pesquisa), IncludeAnnotationCss (controlado por anotação).

ScriptConfig flags: IncludeJQuery (necessário para todos os demais), IncludeBootstrap, IncludeViewerScripts (núcleo: docViewer.js + splitter + links), IncludeSearchScripts e IncludeSearchBar (controlado por pesquisa), 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 }))

Esses auxiliares são a forma suportada de fornecer os recursos do navegador. Aplicações que copiaram docViewer.js, documentLinks.js e docViewer.UI.js para wwwroot devem remover essas cópias assim que a página for renderizada a partir das tags emitidas.