Visualizador

A classe principal de visualização de documentos

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 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 Visualizador Funciona).

OpenDocumentAsync

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

SobrecargaQuando usar
Task<string> OpenDocumentAsync(string filePath, DocOptions? options = null, CancellationToken ct = default)Abrindo a partir do disco com detecção automática de formato e a configuração padrão do formato
Task<string> OpenDocumentAsync(string filePath, BaseConfig? config, DocOptions? options = null, CancellationToken ct = default)Você precisa de opções de renderização por formato (PdfConfig, WordConfig, …)
Task<string> OpenDocumentAsync(Stream stream, FileInfo fileInfo, BaseConfig? config = null, DocOptions? options = null, CancellationToken ct = default)O documento não é um arquivo no disco (upload, banco de dados, blob). fileInfo deve conter a extensão correta — ela orienta a detecção de formato
csharp
// 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

text
void CloseDocument(string token)

Remova a sessão do cache (descartando o mecanismo 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

text
int GetPageCount(string token)

Total de páginas da sessão aberta. Lança InvalidOperationException (Document session not found. Please re-open document.) se o token for desconhecido ou expirado, e ArgumentException para um token vazio.

GetPageDimensions

text
(int Width, int Height) GetPageDimensions(string token, int page = 1)

O tamanho de página renderizado padrão do documento com zoom de 100% — o espaço de coordenadas para anotações construídas em código. page é aceito por compatibilidade; o resultado é o padrão do documento. Lança InvalidOperationException (Document session not found. Please re-open document.) se o token for desconhecido ou expirado, e ArgumentException para um token vazio.

GetWorksheetNames

text
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.

Somente 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 InvalidOperationException (Document session not found. Please re-open document.) se o token for desconhecido ou expirado, e ArgumentException para um token vazio.

Adicionado em 26.9.0.

Bandeiras de capacidade

MembroSignificado
bool IsSearchEnabledA licença atual concede Search
bool IsAnnotationEnabledA licença atual concede Annotation

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

Opções de Documento

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

TipoPropriedadePadrãoDescrição
stringPassword""Senha para documentos protegidos (copiada automaticamente para a configuração de formato).
intImageResolution0Obsoleto. Mantido apenas para compatibilidade — defina ImageResolution na configuração de formato em vez disso.
stringWatermark""Texto de marca d'água personalizado desenhado nas páginas renderizadas. String de formato: "^Text~Color~FontSize~FontName~Opacity~Angle", por exemplo "^Sample Copy~Red~24~Verdana~80~-45".
intTimeOut60Expiração deslizante da sessão em minutos.
boolIsSecuredtrueNão aplicada atualmente — reservada. A vinculação de token é controlada globalmente por DoconutOptions.UnsafeMode (veja Conceitos Principais → Sessões e Segurança).

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

TipoPropriedadePadrãoDescrição
boolIsWebFarmfalseObsoleto — não tem efeito. Publique o documento com DistributedDocumentPublisher.PublishAsync (ou IDistributedPublishQueue.EnqueueAsync) e defina FileShareConfig.RootPath em vez disso.
stringWebFarmPath""Obsoleto — não tem efeito. Use FileShareConfig.RootPath em vez disso.
boolEditModefalseReservado para o fluxo de trabalho do Editor distribuído separadamente; deixe false para o visualizador padrão.

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
^Text~Color~FontSize~FontName~Opacity~Angle
csharp
string token = await viewer.OpenDocumentAsync(
    path,
    new PdfConfig(),
    new DocOptions
    {
        Watermark = "^Confidential~Red~24~Verdana~80~-45",
        TimeOut = 30
    });
CampoExemploSignificado
Inicial ^^Layout opcional de todos os cantos. Sem ele, a colocação normal da marca d'água é usada.
TextoConfidentialTexto renderizado em cada página. Não pode estar vazio.
CorRedCor nomeada compreendida pela camada de desenho.
FontSize24Tamanho da fonte; entrada numérica inválida recai para o padrão do renderizador.
FontNameVerdanaFamília de fonte solicitada. Certifique‑se de que está instalada no ambiente de implantação.
Opacity80Valor de byte de 0 a 255. Deve ser analisado com sucesso.
Angle-45Ângulo de rotação em graus; entrada numérica inválida recai para o padrão.

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

Estado da licençaValor personalizado fornecidoResultado renderizado
Licença de visualizador paga válidaNãoPágina limpa
Licença de visualizador paga válidaSimMarca d'água personalizada
Visualizador base Temporário/Demo ativoNãoPágina limpa do visualizador base
Visualizador base Temporário/Demo ativoSimMarca d'água personalizada quando o caminho limpo do visualizador base se aplica
Licença ausente, rejeitada, expirada, de versão incorreta ou de domínio inválidoQualquerMarca d'água de aplicação/avaliação; o valor personalizado não a substitui
Renderização de plugin sob regras de avaliaçãoQualquerMarca d'água de avaliação

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. Uma marca d'água personalizada é, portanto, 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 interface é:

MembroPropósito
AnnotationManager GetAnnotationManager(string token)Gerenciador vinculado às dimensões da página da sessão aberta
AnnotationManager GetAnnotationManager(string token, int pageWidth, int pageHeight)Gerenciador com dimensões de página explícitas
AnnotationManager GetAnnotationManager(int pageWidth, int pageHeight)Gerenciador independente de sessão
void LoadAnnotationData(string token, AnnotationManager manager)Carregar anotações criadas em C# na sessão
void LoadAnnotationData(string token, string annotationData)Carregar anotações da página codificada/envelope Base64 retornado por AnnotationManager.GetAnnotationData()
void LoadAnnotationXML(string token, XmlDocument annotationXml)Carregar anotações de XML
XmlDocument GetAnnotationXML(string token)Exportar as anotações da sessão como XML
Task<byte[]> ExportAnnotationsToPdfAsync(string token, int zoom = 100, CancellationToken ct = default)PDF com anotações incorporadas
Task<int> ExportAnnotationsToPngAsync(string token, string directoryPath, int zoom = 100, CancellationToken ct = default)Um PNG por página, anotações incorporadas, gravado em directoryPath (criado se ausente); retorna o número de imagens gravadas
Task<byte[]> ExportAnnotationsToPngZipAsync(string token, int zoom = 100, CancellationToken ct = default)ZIP de PNGs por página com anotações incorporadas

Metadados DICOM

text
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 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.

text
string ReferenceCss(CssConfig? config = null)      // null → Bootstrap + visualizador + pesquisa + anotação
string ReferenceScripts(ScriptConfig? config = null)

CssConfig flags: IncludeBootstrapCss, IncludeViewerCss, IncludeSearchCss (controlado por busca), 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 busca), IncludeAnnotationScripts e IncludeAnnotationBar (controlado por anotação), EmitFeatureFlags (padrão true: também grava um script window.Doconut.features = { search, annotation, editor } inline; defina como false sob uma Content-Security-Policy que bloqueia scripts inline).

html
@inject Doconut.Viewer Viewer

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

Esta página foi útil?