Visualizador

Viewer (namespace Doconut) é o ponto de entrada público para abrir documentos a partir de controladores MVC, páginas Web Forms e manipuladores. É um serviço transient composto por DoconutHost.Initialize; resolva‑o onde você o utiliza:

var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();

new Viewer() também funciona depois que DoconutHost.Initialize for executado — ele resolve os mesmos serviços — o que mantém o código migrado do pacote clássico compilando. Antes de Initialize, ele lança InvalidOperationException.

Viewer não mantém estado de documento por requisição e intencionalmente não implementa IDisposable: as sessões de documento vivem independentemente dele, portanto descartar um Viewer nunca poderia fechar um documento aberto (veja Como o Visualizador Funciona).

OpenDocumentAsync

Abre um documento e devolve o token de sessão que o widget usa em todas as solicitações subsequentes. Quando UnsafeMode está false (o padrão), o token é concedido à sessão ASP.NET da requisição atual — chame‑o a partir de uma requisição que possui estado de sessão (veja Sessões e Segurança).

// 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 (HttpPostedFileBase no MVC; HttpPostedFile no Web Forms)
using (var ms = new MemoryStream())
{
    await file.InputStream.CopyToAsync(ms);
    ms.Position = 0;
    token = await viewer.OpenDocumentAsync(ms, new FileInfo(Path.GetFileName(file.FileName)));
}

Exceções a tratar:

• LicenseException — uma licença foi encontrada mas rejeitada (a mensagem contém o motivo), ou o formato necessita de uma capacidade de plugin que a licença não concede.
• FormatNotSupportedException — nenhum visualizador lida com a extensão do arquivo.
• InvalidDataException — o conteúdo está corrompido ou não corresponde à sua extensão.

OpenDocument (synchronous)

Para código-behind de Web Forms e outro código que não usa páginas assíncronas:

string OpenDocument(string filePath, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(Stream stream, string fileName, BaseConfig? config = null, DocOptions? options = null)
string OpenDocument(byte[] bytes, string fileName, BaseConfig? config = null, DocOptions? options = null)

Cada um devolve o token e também o armazena em viewer.Token. fileName deve conter a extensão correta. Esses wrappers são seguros para serem chamados a partir de uma página Web Forms: o caminho de abertura nunca retoma no contexto de requisição do ASP.NET, portanto aguardar por ele não pode causar deadlock. O mesmo não é verdade para todas as APIs assíncronas do Doconut — veja a seção Web Forms de Plugin Conversor.

FecharDocumento

void CloseDocument(string token)

Remove a sessão (liberando o motor de documentos imediatamente), remove a concessão do token da sessão ASP.NET da requisição atual e revoga o token. Opcional — a expiração deslizante realiza a mesma limpeza — mas é recomendada para documentos grandes.

Consultas de sessão

Cada um lança exceção se o token for desconhecido ou expirado.

Opções de Documento

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

Marca d'água personalizada

DocOptions.Watermark aceita 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 por um texto Invalid Watermark visível em vez de desaparecer silenciosamente.

Decisão de Licença

A mesma decisão se aplica às páginas servidas e às exportações de anotações. Uma marca d'água personalizada é um recurso de um aplicativo licenciado, não um meio de substituir a marca d'água de avaliação.

API de Anotações

Carregamento e exportação de anotações no lado do servidor. O tutorial está em Anotações.

Metadados DICOM

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

Neste pacote ele sempre devolve null, e a solicitação de metadados do widget responde 501 Not Implemented: a leitura de tags DICOM não está disponível no .NET Framework. O renderização de DICOM — páginas, quadros e animação — funciona. Veja Plugin DICOM.

Auxiliares de recurso — ReferenceCss / ReferenceScripts

Emita as tags <link> e <script> para os recursos que o módulo de recursos serve sob DoconutOptions.ResourcesPath, na ordem de dependência. Os arquivos para recursos controlados por licença (Search, Annotation) são emitidos somente quando a licença os concede.

string ReferenceCss(CssConfig? config = null)       // null → Bootstrap + viewer + search + annotation
string ReferenceScripts(ScriptConfig? config = null)
bool IsSearchEnabled { get; }                       // estado da licença, para proteger código de init da ribbon
bool IsAnnotationEnabled { get; }

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

Sinalizadores ScriptConfig: IncludeJQuery (necessário para todos os demais), IncludeBootstrap, IncludeViewerScripts (os scripts principais do visualizador), IncludeSearchScripts e IncludeSearchBar (controlado por busca), IncludeAnnotationScripts e IncludeAnnotationBar (controlado por anotação).

Ambos retornam HTML: escreva‑os com @Html.Raw(...) no MVC 5 (produza‑os no controlador — as visualizações não têm @inject) ou <%= %> no Web Forms. Início Rápido mostra ambos.

Renderizador de Visualizador

string RenderViewer(string elementId, string token, ViewerConfig? config = null)

Retorna um bloco <script> que inicializa o widget no elemento com id elementId e exibe o documento: docViewer({...}) construído a partir do ViewerConfig (padrão: BasePath: '/', ResPath: 'doconut-res/images'), depois .View(token). Escreva‑o após os scripts do visualizador. O script gerado não mantém referência ao objeto do visualizador, portanto uma página com sua própria barra de ferramentas deve inicializar o widget manualmente. Veja Configurações do Visualizador.

Fazenda Web

string? AccessToken contém o ticket assinado emitido pela abertura mais recente quando o modo distribuído está ativo e UnsafeMode está false; ele está null em um único servidor. Envie‑o ao widget com o token: objViewer.View(token, access).