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.

Viewer não mantém estado por solicitaçã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 Visualizador Funciona).

OpenDocumentAsync

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

// Abertura simples
string token = await viewer.OpenDocumentAsync(path);

// Com configuração e opções por formato
token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig { AllowSearch = true, AllowCopy = true },
    new DocOptions { TimeOut = 30 });

// De um 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. A expiração do 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 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 um único host:

Marca d'água personalizada

DocOptions.Watermark usa seis campos separados por til (~). Um ^ opcional no início solicita o layout de 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 animada é 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 não-DICOM.

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 + visualizador + pesquisa + anotação
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 outros), IncludeBootstrap, IncludeViewerScripts (núcleo: docViewer.js + divisor + 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 }))

GetWorksheetNames

IReadOnlyList<string> GetWorksheetNames(string token)

Retorna os nomes das planilhas de uma planilha aberta, na ordem da pasta de trabalho, ou uma lista vazia quando o documento aberto não é uma planilha.

Adicionado em 26.9.0.