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ã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. Cada abertura é assíncrona — não existe OpenDocument síncrono.

// 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 uma capacidade de plugin que não é mais concedida. O vencimento 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.

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.

Apenas as planilhas renderizadas são listadas: planilhas ocultas e vazias são excluídas, e quando ExcelConfig.SheetNames restringe a renderização, apenas essas planilhas aparecem. Uma planilha nem sempre corresponde a uma página — uma muito grande é renderizada em várias páginas. Lança exceção se o token for desconhecido ou expirado.

Adicionado em 26.9.0.

Bandeiras de capacidade

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

Opções de Documento

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 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 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 superfície é:

Cada um desses requer o token da sessão. O formato GetAnnotationManager(pageWidth, pageHeight) sem sessão da biblioteca anterior 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 Recursos — 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 apenas 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 demais), 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 }))

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.