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 minimalistas. Ele é 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 expôs 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 Visualizador 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.

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
// Abrir 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 precisa 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 uma 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)

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

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 a 100% de zoom — 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.

ObterNomesDasPlanilhas

text
IReadOnlyList<string> GetWorksheetNames(string token)

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

Apenas 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 em branco.

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 Ribbon licenciada somente quando o servidor realmente a fornecerá — veja Início rápido.

Opções de Documento

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

TipoPropriedadePadrãoDescrição
stringPassword""Senha para documentos protegidos (copiada automaticamente para a configuração de formato).
intImageResolution0Obsoleto. Mantido apenas por compatibilidade — defina ImageResolution na configuração de formato em vez disso.
stringWatermark""Texto de marca‑á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. Observe a capitalização — a biblioteca anterior escrevia isso como IsWebfarm.
stringWebFarmPath""Obsoleto — não tem efeito. Use FileShareConfig.RootPath, conforme descrito em Implantações Distribuídas. Anteriormente escrito como WebfarmPath.
boolEditModefalseReservado para um fluxo de trabalho de edição distribuído separadamente; deixe false para o visualizador padrão.

Marca‑água personalizada

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

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 de cantos completos opcional. Sem ele, a colocação normal da marca‑á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 esteja 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 de visualizador base limpa
Visualizador base temporário/demo ativoSimMarca d'água personalizada quando o caminho de visualizador base limpo 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 de GIF animado é carimbada quadro a quadro. Portanto, uma marca d'água personalizada é 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 é:

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 construídas 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

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

Metadados DICOM

text
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 busca e anotação, são emitidos apenas 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 + viewer + search + annotation
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 inline window.Doconut.features = { search, annotation, editor }; 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 }))

Esses auxiliares são a forma suportada de entregar 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.

Esta página foi útil?